
# Migrace na v7

Tento průvodce popisuje změny, které je třeba provést při přechodu z Blockstudio 6 na verzi 7.

## Importy modulů ES

### Nový prefix `npm:` (doporučeno)

Blockstudio 7 zavádí nový prefix `npm:` pro importy modulů ES, který odpovídá konvenci specifikátoru [Denonpm](https://docs.deno.com/runtime/fundamentals/node/#using-npm-packages).

**Předtím (v6):**

```javascript
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
```

**Poté (v7):**

```javascript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
```

### Importy CSS

Stejná změna platí i pro importy CSS:

**Předtím (v6):**

```javascript
import "blockstudio/swiper@11.0.0/swiper.min.css";
```

**Poté (v7):**

```javascript
import "npm:swiper@11.0.0/swiper.min.css";
```

### Zpětná kompatibilita

Prefix `blockstudio/` zůstává podporován kvůli zpětné kompatibilitě. Váš stávající kód bude dál fungovat beze změn. Doporučujeme však přejít na prefix `npm:`, aby byl v souladu s širším ekosystémem JavaScript.

Prefix `npm:` má několik výhod:

- **Soulad s ekosystémem** – odpovídá zavedené konvenci Deno
- **Přehlednost** – hned je jasné, že importujete z npm
- **Připravenost na budoucnost** – prefix `blockstudio/` může být v některé budoucí hlavní verzi zastaralý

## Názvy hooků

Verze 7 Blockstudio sjednocuje názvy všech hooků PHP: místo `camelCase` používá `snake_case`, v souladu se základními konvencemi WordPress.

### Změněné názvy hooků

| Starý název (v6) | Nový název (v7) |
|---------------|---------------|
| `blockstudio/blocks/components/useblockprops/render` | `blockstudio/blocks/components/use_block_props/render` |
| `blockstudio/blocks/components/innerblocks/render` | `blockstudio/blocks/components/inner_blocks/render` |
| `blockstudio/blocks/components/innerblocks/frontend/wrap` | `blockstudio/blocks/components/inner_blocks/frontend/wrap` |
| `blockstudio/blocks/components/richtext/render` | `blockstudio/blocks/components/rich_text/render` |
| `blockstudio/assets/process/scss/importPaths` | `blockstudio/assets/process/scss/import_paths` |
| `blockstudio/settings/assets/process/scssFiles` | `blockstudio/settings/assets/process/scss_files` |
| `blockstudio/settings/editor/formatOnSave` | `blockstudio/settings/editor/format_on_save` |
| `blockstudio/settings/blockEditor/disableLoading` | `blockstudio/settings/block_editor/disable_loading` |
| `blockstudio/settings/blockEditor/cssClasses` | `blockstudio/settings/block_editor/css_classes` |
| `blockstudio/settings/blockEditor/cssVariables` | `blockstudio/settings/block_editor/css_variables` |
| `blockstudio/settings/ai/enableContextGeneration` | `blockstudio/settings/ai/enable_context_generation` |

### Zpětná kompatibilita

Staré názvy hooků ve stylu camelCase zůstávají podporovány kvůli zpětné kompatibilitě. Váš stávající kód bude dál fungovat beze změn. Kvůli jednotnosti však doporučujeme přejít na nové názvy ve stylu snake_case.

**Příklad migrace:**

```php
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
    return ['my-stylesheet'];
});

// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
    return ['my-stylesheet'];
});
```

## Kanonické značky bloků

Verze 7.6 Blockstudio nadále umožňuje používat prefixy projektů a přesné aliasy jako body rozšíření za běhu, ale v příkladech, výstupech katalogu, deklaracích vykreslování a diagnostice používá jako kanonický zápis `<bs:namespace-slug>`. Kanonické značky obsahují skutečný registrovaný název bloku a nezávisí na filtru konkrétního hostitele.

Pro projekt s `brand => ["theme-components"]` a `ui => ["bsui"]`:

```html
<!-- Legacy project shorthand -->
<brand-card>
  <ui-input />
</brand-card>

<!-- Canonical output -->
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>
```

Samostatný migrační příkaz zmapuje existující projekt a přepíše zkrácené zápisy na kanonický tvar. Nejprve vytvoří přehled, při nevyřešených případech se zastaví a mění pouze názvy značek. Příkaz, jeho vstupy a bezpečnostní chování najdete v dokumentaci [Migrace značek bloků](https://blockstudio.dev/cs/docs/dev/cli/#block-tag-migration).

## Pojmenování souborů assetů

Verze 7 Blockstudio zavádí tečkovou notaci přípon souborů assetů, která nahrazuje dosavadní zápis s pomlčkou jako doporučenou konvenci.

### Změněné názvy souborů

| Starý název (v6) | Nový název (v7) |
|---------------|---------------|
| `*-inline.(s)css` | `*.inline.(s)css` |
| `*-inline.js` | `*.inline.js` |
| `*-editor.(s)css` | `*.editor.(s)css` |
| `*-editor.js` | `*.editor.js` |
| `*-scoped.(s)css` | `*.scoped.(s)css` |
| `*-view.js` | `*.view.js` |

### Zpětná kompatibilita

Starý zápis s pomlčkou zůstává podporován kvůli zpětné kompatibilitě. Vaše stávající soubory budou dál fungovat bez přejmenování. U nových bloků však doporučujeme přejít na tečkovou notaci.

**Příklad migrace:**

```
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css   →  style.inline.css
├── style-scoped.css   →  style.scoped.css
├── style-editor.css   →  style.editor.css
├── script.js
├── script-inline.js   →  script.inline.js
├── script-editor.js   →  script.editor.js
└── script-view.js     →  script.view.js
```

## Přepínač polí

Vlastnost `switch` má nyní výchozí hodnotu `false` místo `true`. Ve verzi v6 mělo každé pole na levém okraji neviditelný přepínač, který byl ve výchozím stavu zapnutý. Ve verzi v7 je přepínač volitelný a používá viditelnou ikonu oka v popisku pole.

### Co se změnilo

- **Výchozí hodnota je nyní `false`**: pole už nemají přepínač, pokud výslovně nenastavíte `"switch": true`
- **Viditelná ikona oka**: místo skryté klikací oblasti vlevo se v oblasti popisku zobrazí tlačítko s ikonou oka
- **Překryv při deaktivaci**: když je pole deaktivované, zobrazí se rozmazaný překryv s textem „Toto pole je deaktivované“ místo pouhého snížení neprůhlednosti

### Migrace

Pokud jste spoléhali na výchozí chování přepínače ve verzi v6, musíte ho výslovně zapnout:

```json
{
  "id": "title",
  "type": "text",
  "label": "Title",
  "switch": true
}
```

Pokud jste dříve nastavili `"switch": false`, abyste přepínač deaktivovali, můžete toto nastavení odstranit, protože `false` je nyní výchozí.

## Tailwind CSS

Verze 7 Blockstudio zcela nahrazuje přístup v6 Tailwind. Ve verzi v6 se Tailwind CSS kompilovalo na straně klienta pomocí CDN v editoru a při uložení příspěvku se ukládalo na disk. Ve verzi v7 se Tailwind CSS kompiluje na straně serveru při každém požadavku na frontend pomocí [TailwindPHP](https://github.com/dnnsjsk/tailwindphp) s automatickým ukládáním do mezipaměti podle souborů.

Úplné podrobnosti o novém systému najdete v [dokumentaci Tailwind CSS](https://blockstudio.dev/cs/docs/tailwind/).

### Kompilace na straně serveru při každém požadavku

Když je `tailwind.enabled` nastaveno na `true`, každý požadavek na frontend se kompiluje na straně serveru. Postup kompilace:

1. WordPress vykreslí celou stránku HTML do výstupního bufferu
2. Kandidáti tříd CSS se extrahují z HTML (rychlým regexem, bez kompilace)
3. Kandidáti se seřadí a zahashují spolu s konfigurací CSS, čímž vznikne klíč mezipaměti
4. Při zásahu do mezipaměti se načte soubor CSS z mezipaměti a vloží se
5. Při minutí mezipaměti TailwindPHP zkompiluje CSS, uloží jej do sdílené runtime mezipaměti Blockstudio v rámci rozsahu `tailwind` a vloží jej

Zkompilované CSS se vloží jako vložená značka `<style id="blockstudio-tailwind">` před `</head>`. Zahrnuje preflight Tailwind a všechny odpovídající utility třídy.

Skript CDN zůstává v editoru aktivní pouze pro živý náhled. Na frontend se nikdy neposílá.

### Změna formátu `config`

Vlastnost `config` se změnila z objektu JSON (Tailwind v3) na řetězec CSS (syntaxe Tailwind v4 CSS jako první).

**Předtím (v6):**

```json
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}
```

**Poté (v7):**

```json
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}
```

### Odebrané nastavení `customClasses`

Nastavení pole `customClasses` bylo odebráno. V přístupu Tailwind v4, který upřednostňuje CSS, se vlastní utility třídy definují přímo v řetězci `config` pomocí `@layer utilities`.

**Předtím (v6):**

```json
{
  "tailwind": {
    "customClasses": [
      { "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
      { "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
    ]
  }
}
```

**Poté (v7):**

```json
{
  "tailwind": {
    "config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
  }
}
```

Nebo pomocí filtru pro víceřádkové konfigurace:

```php
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
```

Byl odebrán také filtr `blockstudio/settings/tailwind/custom_classes`. Chcete-li přidat vlastní pravidla CSS, použijte místo něj filtr `blockstudio/tailwind/css`.

### Odebraný endpoint REST

Endpoint `POST /blockstudio/v1/editor/tailwind/save` byl odebrán. Zkompilované CSS se už neukládá z editoru. Pokud jste měli vlastní kód, který tento endpoint volal, můžete ho bezpečně odstranit.

### Ukládání do mezipaměti

Blockstudio používá strategii ukládání do mezipaměti založenou na kandidátech. Namísto hashování celého HTML stránky (což by při každém požadavku zneplatnilo mezipaměť kvůli jednorázovým tokenům a časovým razítkům) se hashují pouze kandidáti tříd CSS. To znamená:

- Stránky se stejnými třídami CSS sdílejí stejný soubor v mezipaměti
- Dynamický obsah (jednorázové tokeny, panely administrace, časová razítka) nezpůsobí neplatnost mezipaměti
- Mezipaměť se zneplatní pouze při změně množiny tříd CSS nebo konfigurace

Soubory mezipaměti se ukládají do nakonfigurovaného kořenového adresáře runtime Blockstudio v `sites/{network-blog}/{runtime-identity}/tailwind/`. Opětovnou kompilaci vynutíte zavoláním `Blockstudio\Runtime_Cache::purge('tailwind')`.

### Změny filtrů

| Starý název (v6) | Nový název (v7) |
|---------------|---------------|
| `blockstudio/tailwind/on_demand/css` | `blockstudio/tailwind/css` |
| `blockstudio/tailwind/assets/dir` | Odebráno |
| `blockstudio/settings/tailwind/custom_classes` | Odebráno |

### Odebrané soubory a načítání

Ve verzi v6 se Tailwind CSS načítalo jako externí šablony stylů (`blockstudio-tailwind`, `blockstudio-tailwind-preflight`). Ve verzi v7 se všechen CSS vkládá přímo pomocí výstupního bufferu. Na frontendu se pro Tailwind nevkládají žádné značky link ani šablony stylů.

## Knihovna bloků

Vestavěná knihovna „Blockstudio Elements“ byla odebrána. Nastavení `library` ve verzi `blockstudio.json` ani filtr `blockstudio/settings/library` již nemají žádný účinek.

Pokud jste používali bloky z knihovny (Galerie, Posuvník, Porovnání obrázků, Kód, Ikona), zkopírujte složky bloků z adresáře `includes/library/blockstudio-element/` instalace v6 do adresáře blockstudio své šablony a aktualizujte jejich soubory `block.json` novými názvy a kategoriemi.
