Co návod slibuje a co ne

Meze jsou po kapitolách rozeseté tam, kde na ně narazíte při práci. Tahle stránka je má na jednom místě, aby se daly přečíst dřív, než se šablona kupuje nebo než se slíbí termín. Nic tu není navíc oproti zbytku návodu — je to výtah.

U každé meze stojí, co znamená prakticky a proč platí. To druhé není omluva: mez, u které víte důvod, se dá obejít, kdežto mez bez důvodu se dá jen respektovat, nebo se do ní opřít.

Šablona přibere Svelte

Prakticky: i čistě Astro šablona potřebuje @astrojs/svelte, svelte.config.js a dva @source řádky v CSS. Platí to i pro náhradu bloku — komponenta, kterou podstrčíte, musí být taky Svelte.

Proč: bloky jsou Svelte komponenty a náhrada se uplatňuje uprostřed jejich serverového renderu. Astro komponenta tam být nemůže, protože se vykresluje na statické HTML a nemůže dodat to, co ten vzor potřebuje.

Obejít to jde jen jedním způsobem, a je legitimní: typ obsahu může mít tělo vypnuté (body: "none"). Web postavený jen na typovaných polích a výpisech žádné bloky nekreslí, takže nepotřebuje ani Svelte — je celý na datové půlce.

A obal je levnější, než to zní: .svelte soubor s $props() a vaším značkováním. Runy (reaktivita Svelte) nepotřebuje, dokud v něm nechcete něco interaktivního.

Redaktor v editoru uvidí jinou podobu než návštěvník

Dvě meze, obě z téhož důvodu.

Náhled v administraci kreslí bloky s výchozími hodnotami rolí, ne s barvami vašeho webu. Struktura a role sedí („tohle je pruh s akcentem“), odstín ne.

Náhradu bloku editor nevidí vůbec. Redaktor uvidí náš blok i tam, kde na webu bude vaše komponenta.

Proč: administrace obsluhuje víc webů naráz, takže podoba jednoho by ostatním lhala. Spravilo by to teprve načtení hodnot toho webu, který se zrovna edituje — ale to je vlastní rozhodnutí, ne vedlejší efekt.

Co s tím prakticky: řekněte to redaktorovi předem. Rozdíl mezi „editor ukazuje strukturu“ a „editor ukazuje výsledek“ je věta, kterou snese na začátku a špatně ji nese ve chvíli, kdy si myslí, že jste mu rozbili web.

Nahradit nejde diskuse ani blok z pluginu

Diskuse (blok Comments) je jediný blok, který v prohlížeči potřebuje JavaScript, a kreslí ho Astro jmenným importem, ne renderer. Náhrada by se tiše neuplatnila, což je ta nejhorší varianta — proto ji mapa mezi klíči nemá a překlad na to upozorní.

Blok, který dodal plugin, do mapy taky nespadá. Jeho jméno má tvar <slug>:<jméno> a zapíná se pro každý web zvlášť; patří tomu pluginu, ne šabloně.

Co s tím prakticky: diskusi obarvíte rolemi jako každý jiný blok a texty kolem ní si dodáváte vy (katalog vět v CommentsView), takže se z ní beze změny komponenty dá udělat hodně. Když to nestačí, zbývá blok v editoru nepoužít a formulář si postavit vlastní nad prostředníky z balíku.

Náhrada bloku RichText se netýká těla položky

Formátovaný text se na stránku dostane dvěma cestami a náhrada platí jen pro tu první:

• Blok RichText uvnitř těla složeného z bloků — ten mapa nahradí normálně.
• Tělo položky typu „formátovaný text“ — to kreslí RichTextBody, kterou si ve své routě voláte vy sami. Žádný blok v něm není, takže není co v mapě hledat.

Prakticky to znamená, že šablona, která si RichText nahradí, bude mít dvě typografie podle druhu těla — pokud si tu druhou nepohlídá. Řešení je na dosah a je celé ve vaší routě: místo <RichTextBody data={entry.content} /> zavolejte tutéž komponentu, kterou dáváte do mapy. Sdílené CSS (@patro/shared/richtext.css) mluví rolemi, takže při pouhém přebarvení se ty dvě cesty rozejít nemůžou; rozejdou se teprve náhradou.

Token spraví barvu, ne tvarosloví

Prakticky: slovník rolí pokrývá barvy — text, plochy, hrany, akcent. Zaoblení rohů, vnitřní odsazení a rytmus bloků zatím tokenizované nejsou (pruh výzvy má rounded-3xl px-6 py-10 napevno).

Proč: tokenizovat jde i to, ale je to další rozhodnutí a dělá se až potom, co se usadí barvy — na nich se pozná, jestli slovník rolí vůbec sedí.

Co s tím prakticky: když má vaše šablona výrazně vlastní tvarosloví, počítejte u pár nejnápadnějších bloků (hero, výzva, karta) rovnou s náhradou komponentou. Zbytek palety obarvení unese.

Oživuje se jen první úroveň

Prakticky: blok vložený do „Sekce“ nebo „Sloupců“ se vykreslí staticky. U diskuse to redaktorovi nedovolí ani editor.

Proč: oživit blok uvnitř stromu, který kreslí Svelte renderer zevnitř, by znamenalo prošít hydrataci celým rendererem — a z každé stránky by se stal ostrůvek se vším JavaScriptem, který k tomu patří. Dnes je interaktivní blok jeden jediný, takže se ta cena nevyplatí.

Token nejde vydat užší

Prakticky: není volba „jen pro čtení“. Kdo má tenant token, umí kromě čtení i těch pár zápisů, které veřejné API má — hlášení nenalezených adres, ohlášení oblastí widgetů a dvě věci prostředníkem: odeslání komentáře a přepnutí palce pod ním.

Proč: rozlišovat „smí hlásit vlastní čtyřistačtyřky“ od „nesmí“ nikdo nepotřeboval, a dokud byl veřejný zápis jediný, jinou hranici rozsah nekreslil. U komentářů a palců hranice je, jenže rozsahy k ní pořád nikdo nepostavil. Nejsou tedy dnes k dispozici a jejich doplnění je práce na naší straně.

Co drží hranici místo toho: příslušnost k webu. Token z jednoho webu na obsah jiného nedosáhne a všechny čtyři zápisy míří výhradně do dat toho webu, kterému token patří — a mají vlastní stropy. Rozvaha je v kapitole o napojení.

Náhledový odkaz míří na jednu adresu pro celou instalaci

Prakticky: adresu veřejného webu, ze které administrace skládá odkaz na náhled, drží jedna hodnota pro celé patro, ne každý web svou. Když má vaše instalace víc webů s vlastními doménami, může redaktor dostat odkaz mířící na cizí web.

Proč: je to vědomý zbytek jednowebového předpokladu z doby, kdy patro obsluhovalo jeden pilot. Adresa je jedna pro celou instalaci a rozpad na adresu per web je vlastní práce na naší straně, ne přepínač v nastavení.

Co s tím prakticky: izolace tím netrpí — token náhledu patří jednomu webu a cizí web ho odmítne. Špatný je jen ten odkaz, ne přístup. Než se to spraví, je oprava mechanická: v odkazu se přepíše doména na tu vaši, zbytek (cesta i ?preview=) platí beze změny.

Jedna instance webu obsluhuje jeden web patra

Prakticky: odkládací paměť navigace, oblastí a diskuse ani stav ohlašování nemají rozměr „pro který web“ — vyrábějí se z tokenu jednoho workeru.

Proč: klient se staví z tokenu v prostředí a ten je pro celou instanci jeden.

Co s tím prakticky: kdo chce jedním workerem obsloužit víc webů, musí vyrobit instanci na každý z nich. Běžné nasazení „jeden web = jeden worker = jeden token“ se o tohle nezavadí.

Obsah je živý, takže patro musí být dosažitelné

Prakticky: stránky se skládají za běhu, ne při buildu. Nedostupné patro znamená, že není čím naplnit obsah.

Proč: redaktor publikuje a čeká, že to je hned venku — build na každou změnu by to popíral.

Co s tím prakticky: balík má hotovou odpověď (loadContent, isOutage, outageResponse), takže z výpadku vyjde čitelná stránka „web je chvíli mimo“ s 503, ne pětistovka. Ozdoba (navigace, patička, výpisové bloky) se ošetřuje sama a její výpadek stránku neshodí. Postup je v kapitole o oblastech a diskusi.

Ta stránka je ale napevno česky a přebít se nedá — jediná volba outageResponse je doba do dalšího pokusu. Web v jiném jazyce si stránku výpadku napíše sám a outageResponse nevolá; isOutage je jen zúžení typu, takže se tím o nic dalšího nepřipraví. Co má vlastní stránka napodobit, je v téže kapitole.

Balíky patra nejsou na veřejném registru

Prakticky: @patro/render, @patro/blocks i @patro/shared, ze kterých ukázky v tomhle návodu importují, na npm nenajdete. Jsou to balíky uvnitř našeho repozitáře ("private": true, verze 0.0.0) a žádný krok, který by je publikoval, neexistuje. npm install na ně tedy neplatí — dostanete je od nás spolu s přístupem k projektu.

Proč: dokud šablonu napojuje někdo, s kým máme domluvu, je registr práce navíc bez užitku — a publikovaný balík je závazek na verzování a zpětnou kompatibilitu, který dnes nikdo nepotřebuje.

Co s tím prakticky: než začnete psát, domluvte si, jak balíky dostanete. Zbytek návodu platí beze změny — importy vypadají stejně, ať přijdou z registru, nebo od nás.

Co návod nepokrývá schválně

• Administraci. Návod je pro toho, kdo staví web, ne pro redaktora ani pro toho, kdo patro provozuje.
• Psaní pluginů. Blok z pluginu se na webu vykreslí jako každý jiný, ale jak se plugin píše, je jiné téma.
• Vlastní serializátor formátovaného textu. Patro posílá strom uzlů a HTML z něj skládá @patro/render nad seznamem povolených prvků. Napsat si vlastní „protože je to jen JSON“ znamená vzít si zpátky i tu sanitizaci — a to je rozhodnutí, které se v návodu nepopisuje, protože ho nedoporučujeme.

Jak poznat, že tahle stránka zestarala

Meze se posouvají a stránka psaná z hlavy zestárne dřív než kód. Pět seznamů jmen se proto hlídá testem, ne slibem:

• jména bloků v tabulce k náhradě se porovnávají se skutečným registrem na obě strany, takže nový blok shodí testy dřív, než tabulka zestará;
• jména metod klienta v kapitole o klientovi se porovnávají se skutečným klientem, taky na obě strany;
• druhy polí v kapitole o položkách se porovnávají se skutečným výčtem ve schématu, taky na obě strany;
• role palety ve slovníku rolí se porovnávají se skutečným slovníkem v balíku bloků, taky na obě strany;
• jména, která ukázky importují z @patro/render jako hodnotu (import type se nepočítá, typ za běhu neexistuje), se porovnávají s tím, co balík vyváží — a tohle jediné jen jedním směrem: opačný by z návodu udělal referenční příručku balíku, protože vyváží i věci pro toho, kdo si staví vlastní middleware nebo vlastní odkládací paměť.

Zbytek téhle stránky je próza a platí to, co je u ní napsané — když se to rozejde s chováním, je to chyba návodu, ne vaše.