Diagram a graf na webu jsou po jednom prohlížeči nad tím, co sestavení odvodilo: interaktivní, odkazovatelné a propojené odvozením

152. Diagram a graf na webu jsou každý jedním prohlížečem nad tím, co sestavení odvodilo: interaktivní, odkazovatelné a propojené odvozením

Kontext

Pravidlo project.a-diagram-is-drawn-not-typed přesunulo každý architektonický vztah, který tento repozitář publikuje, z box artu do Mermaid a uvedlo důvod: parsovatelný diagram lze vykreslit, tematizovat, odkazovat a kontrolovat, obrázek ne. Rohatka dosáhla nuly. Web pak využil jednu z těch čtyř vlastností. site/diagrams.js inicializoval Mermaid barvami stránky a skončil: graf závislostí každého úkolu se kreslil v přirozené šířce uvnitř posuvného boxu, žádný diagram neměl adresu a uzel, který byl úkolem, rozhodnutím či příkazem, byl text vedle webu, který má pro každého stránku. Sestavení Mermaid, nejtěžší soubor na webu, se stahovalo blokujícím tagem script.

Web také nekreslil žádný graf. Odvozená čísla vykresluje jako tabulky (úkoly podle milníku a stavu, percentily měření výkonu, zaznamenaná historie změřeného poměru) a ADR 0135 už jmenuje Apache ECharts jako knihovnu pro měřené řady, „až bude vendorována“.

Navazující projekt téhož vlastníka postavil nejdřív interaktivní prohlížeč Mermaid. Prokázal návrh interakce a odkazy na uzly psal do každého diagramu direktivou Mermaid click, přičemž kontrola sestavení drží, že každý takový odkaz jmenuje servírovanou stránku. To je část, kterou tento repozitář převzít nemůže: odkaz napsaný v diagramu je fakt napsaný dvakrát, jednou v registru, který vlastní objekt, a jednou v obrázku.

Rozhodnutí

Jeden viewer pro každý diagram, jedna komponenta pro každý graf a žádný skript na stránku.

1. Sestavení diagram připraví; prohlížeč ho jen nakreslí. Po Zole scripts/site-build spouští scripts/lib/diagrams.mjs nad sestavenými stránkami. Každý <pre class="mermaid"> dostane id diagram-<name>, kde jméno je to, které deklarovala jeho šablona (data-diagram, samo identita z dat: klíč diagrams.json, id milníku), nebo jinak id nadpisu, pod kterým se nachází; seznam uzlů, které jeho zdroj deklaruje; panel nástrojů prohlížeče, skrytý; a seznam odkazů.

2. Odkaz uzlu se odvozuje, nikdy nepíše. Uzel je odkazován, když jeho id, jeho popisek nebo jeden řádek jeho popisku je identitou objektu, kterému vygenerovaná data dávají stránku: úkolu, milníku, rozhodnutí, pravidla, doktríny, příkazu, schopnosti, dokumentu. Popisek, který jmenuje dva objekty, nebo takový, pro který tento web nemá stránku, nelinkuje ani jeden. Direktiva click z Mermaid se nepoužívá. Odvozené odkazy jsou obyčejné značky vedle diagramu, takže o každém z nich rozhoduje scripts/ci/link-check spolu s ostatními odkazy webu a čtenář bez JavaScriptu je má.

3. Diagram a uzel mají adresu. #diagram-<name> je diagram a #diagram-<name>:<node> jeden jeho uzel, stejné schéma, jaké používá navazující prohlížeč, takže odkaz napsaný pro jeden funguje i v druhém. link-check řeší druhý tvar proti uzlům, které build vypsal: odkaz na uzel, který už neexistuje, shodí build.

4. Prohlížeč je site/diagrams.js, načítaný odloženě stránkami, které nesou diagram; sám si stahuje vendorovaný build Mermaid. Rámec je vlastní <pre> diagramu, který si ponechává své id a své místo v pořadí tabulátoru. Zoom, posun, přizpůsobení, celá obrazovka, stažení SVG, sledování hran uzlu, výběr a kopírování aktuální adresy jsou na každé stránce stejné, z ukazatele i z klávesnice. Jeho ovládací prvky jsou markup, který napsal build, takže je scripts/ci/interaction-check drží u specifikace chování diagram a scripts/interaction-probe je prověřuje.

5. Graf je tabulka, deklarovaná. <figure data-chart> kolem tabulky, kterou stránka už vykresluje, kreslí site/charts.js pomocí Apache ECharts: první sloupec je kategorie, každá hlavička označená data-series je řada a čísla se čtou z buněk. Tabulka zůstává. ECharts je připnutá závislost npm zkopírovaná do buildu, stejně jako Mermaid a Cytoscape, a stahuje se, když se graf blíží k viewportu. Řada se kreslí barvou, kterou má odznak stavu její hlavičky, takže barva stavu zůstává deklarací designu.

6. Stylování je jeden ručně psaný styl nad tokeny, share/design/figure.css, importovaný jen webem.

Zamítnuté alternativy

• Direktiva click v Mermaidu s kontrolou buildu na každém cíli. Funguje to a je to druhý zdroj: autor diagramu by psal trasu, kterou generátor už zná.
• Rozkládání odkazů v prohlížeči z publikovaného indexu. O jeden krok buildu méně, ale odkazy by bez JavaScriptu neexistovaly a link-check by je neviděla; odkaz, o kterém kontroly nemohou rozhodnout, je druh, který tento repozitář nepublikuje.
• Vykreslení diagramů do SVG při sestavení. Stále vyžaduje headless prohlížeč v sestavení, což docs/GITHUB_PAGES_ARCHITECTURE.md už zamítlo, a statické SVG nelze překreslit v druhém motivu.
• Graf popsaný blokem voleb JSON na každé stránce. To je skript pro každou stránku pod jiným jménem a druhá kopie čísel. Tabulka už na stránce je, už je odvozená a už je přístupná.
• Přidání stylů do share/design/primitives.css. Ten sheet se kompiluje do commitnutých stylesheetů Cockpitu a UI, které by se změnily kvůli komponentě, kterou žádný z povrchů nenačítá.
• Diagram na úvodní stránce. Sekce úvodní stránky a její rozpočet bajtů jsou deklarovány a rozhodnutím nenese žádný diagram; změna je samostatná revidovaná změna (I2655).

Důsledky

• Každý diagram, který už na webu je, se stal interaktivním a adresovatelným bez úpravy jakéhokoli dokumentu a každý pozdější se jím stane příchodem. Dokument, který chce pro diagram stabilní adresu, mu dá vlastní nadpis.
• Adresa diagramu následuje jeho nadpis. Přejmenování nadpisu změní adresu a link-check selže na každém odkazu na webu, který stále používá starou. Odkazy zvenčí webu chráněny nejsou.
• Parser uzlů čte vývojové diagramy a stavové diagramy. Jiné druhy se kreslí, přibližují a adresují jako celek a nemají odkazy na uzly. Syntaxe Mermaidu, kterou parser špatně přečte, stojí chybějící odkaz nebo chybějící adresu uzlu, nikdy rozbitou stránku.
• Build webu má o jeden průchod Node víc a nepotřebuje node_modules, takže běží i pod --no-css.
• echarts je nová připnutá závislost buildu; build common, který vendoruje, má asi 0,7 MB a vyžadují ho na požádání jen stránky, které nesou graf.
• share/design/figure.css zatím nečte odvození kontrastu (design.contrast); používá jen páry, které primitives.css už dává dohromady. Aby je odvození četlo, sdílet prohlížeč s Cockpitem a UI a odkazovat uzel, který je souborem repozitáře, na jeho zdroj, to je I2656. Kontrola, která drží graf u jeho tabulky, je I2654.