Slovník¶

Slova, která se v dokumentaci opakují. Vždycky nejdřív jednou větou, pak proč to vůbec potřebuje vlastní jméno.

Entita¶

Jedna věc, o které web něco ví. Produkt, článek, pobočka, člověk v týmu.

Není to stránka. Tohle je ten rozdíl, na kterém všechno stojí: entita může být na deseti stránkách, na žádné, nebo jenom ve feedu pro Zboží.cz. Stránka je jedno z míst, kde se entita ukáže — ne to, čím entita je.

Field¶

Jeden údaj entity. Cena, název, popis, fotka.

Má typ (číslo, text, datum, odkaz na jinou entitu) a hlavně příznak translated nebo shared:

shared — jedna hodnota pro všechny jazyky. Cena, EAN, rozměry.
translated — každý jazyk svoje. Název, popis, alt text u fotky.

Rozhoduje se to v návrhu, ne v adminu.

Komponenta¶

Kus stránky, který umí zobrazit data. Hero, výpis produktů, kontaktní formulář, galerie.

Komponenta má datový kontrakt — předem řečeno, co potřebuje na vstupu. Ne „sáhne si do databáze, jak zrovna potřebuje", ale „chce seznam produktů s cenou a fotkou".

Díky tomu jde předem zjistit, na čem stránka závisí, aniž by se musela spustit.

Capability¶

Seznam toho, co je u téhle komponenty povolené.

Nejlíp se to vysvětlí příkladem. Výpis produktů má capability, která říká:

smíš filtrovat podle: kategorie, cena, dostupnost
smíš řadit podle:    cena, novinky, název
maximálně:           48 položek
smíš jít po vazbách: produkt → kategorie, produkt → značka

Cokoli mimo tenhle seznam nejde. Ne že by to bylo špatně napsané — prostě to systém odmítne.

Proč to není otravné

Protože to je jediný důvod, proč můžou existovat všechny ostatní záruky. Když komponenta smí jenom to, co je vyjmenované, tak systém ví, co může nastat. Když smí cokoli, neví nic a musí předpokládat nejhorší — a nejhorší předpoklad je právě to cache:clear ze scénáře 2.

Za volnost jedné komponenty se platí jistotou v celém systému.

Dva různé významy, které se pletou

Runtime capability = co komponenta potřebuje k běhu (JavaScript, lazy loading). Vlastnost implementace.

Authoring capability = co s ní smí dělat redaktor a AI.

Vypadá to podobně, ale je to úplně jinak. „Komponenta potřebuje JavaScript" není přepínač pro redaktora. V debatě (S1) to bylo jedno z míst, kde Claude dostal přes prsty.

Dotaz (query)¶

Otázka do dat, kterou systém rozumí.

Ne SQL. SQL je moc mocné — dá se v něm napsat cokoli, a proto se z něj nedá nic zjistit předem. Tady je dotaz omezená struktura: filtry, řazení, limit, cesty po vazbách. Vejde se do toho podstatně míň než do SQL.

To omezení je záměr, ne nedokonalost. Protože dotaz je omezený, jde u něj předem spočítat:

na čem závisí (→ kešování)
kolik bude asi stát (→ nikdo neshodí web nešťastným filtrem)
jestli ho ten, kdo se ptá, vůbec smí položit (→ oprávnění)

Když to nestačí

Někdy potřebuješ něco, co se do toho prostě nevejde. Na to je pojmenovaný resolver — kus normálního kódu, který napíše vývojář, má jméno, verzi a vlastní deklarované závislosti.

Úniková cesta existuje. Jen má jméno, aby bylo vidět, kdo ji používá.

Revize¶

Jedna neměnná verze entity. Nikdy se nepřepisuje. Úprava vytvoří novou.

Proto jde říct „ukaž mi, jak ten produkt vypadal 3. května" — a proto může release ukazovat na konkrétní revizi, i když se entita mezitím dvacetkrát změnila.

Changeset¶

Jeden balík změn, který se schvaluje a publikuje dohromady.

Redaktor upraví tři produkty, přehodí dvě komponenty a změní jednu URL. To je jeden changeset. Buď se publikuje celý, nebo nic.

Bez tohohle bys měl v historii tisíc jednotlivých úprav a nikdo by nepoznal, které spolu souvisely.

Release (publikační manifest)¶

Přesný seznam toho, z čeho je web složený právě teď.

Neměnný. Nejde ho dodatečně upravit — jde jen vydat nový.

Obsahuje revize entit po jazycích, revize kompozic stránek, verzi design systému, verzi komponent, routovací tabulku, redirecty, indexy pro výpisy a pravidla fallbacku.

Proč zrovna tohle je nejlepší pojem z celé debaty

Původně se řešilo „verzování a historie". Codex to v kole 5 přerámoval na konzistentní release boundary — a to je lepší pojem, protože historie je jenom vedlejší produkt.

Ta podstatná otázka totiž není „co bylo kdy", ale „co spolu bylo ověřené jako fungující celek". To druhé ti umožní se vrátit. První ti jenom přesně zaznamená chaos.

Workspace (preview)¶

Odložený stav, ve kterém se pracuje, než se to vydá.

Funguje jako průhledná fólie položená na aktuální release: co je napsané na fólii, platí; co není, se čte pod ní. Nekopíruje se celý web.

Klient si tak proklikne celý budoucí web včetně menu a výpisů, ne jen náhled jedné stránky.

Design token¶

Pojmenovaná hodnota vzhledu. Místo #0B5FFF se píše barva.primarni.

Jsou ve třech patrech:

patro	příklad	kdo na to sahá
primitivní	`modra.500`, `mezera.4`	jenom designér
sémantické	`povrch.varovani`, `text.tlumeny`	designér a vývojář
komponentové	vnitřek konkrétní komponenty	vývojář komponenty

Věta, kterou si stojí za to zapamatovat

Tokeny jsou slovník, nikoli gramatika.

Zaručí ti stejný odstín modré a stejnou škálu mezer. Nezaručí ti dobrou stránku — layout, hierarchii, rytmus. Ty se z tokenů neposkládají, stejně jako se z dobrého slovníku sama nenapíše dobrá věta.

Tohle byl argument, kterým Claude prohrál spor S1.

Dependency token¶

Poznámka „tahle stránka závisí na tomhle údaji".

Vzniká sám při sestavování stránky. Nikdo ho nepíše ručně, a proto se na něj nedá zapomenout — což je celý trik ze scénáře 2.

Ke každému tokenu patří číslo (generace), které se při změně zvedne. Cache si pamatuje, jaká čísla platila při sestavení; když se přestanou shodovat, je záznam neplatný.

Druhy vazeb (hrany)¶

Jak spolu entity souvisí. Vazba má vždycky druh:

druh	česky	pravidlo
`owns`	vlastní	jenom jeden vlastník, nesmí vzniknout kruh
`references`	odkazuje se	kolik chceš, kruhy povolené
`classifies`	zařazuje	kolik chceš
`navigates`	je v menu	samostatná struktura
`routes-to`	vede sem URL	samostatná vrstva

To „má vždycky druh" je podstatné. Vazba bez druhu — prostě „tohle nějak souvisí s tímhle" — je podle debaty ta nejrychlejší cesta k systému, kterému nikdo nerozumí.

Fallback¶

Co se ukáže, když překlad chybí.

Znělo by rozumně „prostě ukaž češtinu". Jenže z toho plyne řetěz otázek: Jaká URL se zobrazí? Počítá se ta stránka do německé sitemapy? A hlavně — když se vydá čeština, změní se tím německá stránka?

Proto je fallback pravidlo, které je součástí releasu, ne výchozí chování. A fallback obsahu není totéž co fallback URL; to jsou dvě různá rozhodnutí.