Diagramy a grafy

Každý diagram, který tento web publikuje, kreslí jeden prohlížeč a každý graf jedna komponenta. Žádné se nenastavuje po stránkách. Diagram je blok ```mermaid v jediném dokumentu, který vztah uvádí, nebo zdroj Mermaid, který šablona zapíše z generovaných dat; graf je tabulka, kterou stránka už vykresluje. To, co je činí interaktivními, adresovatelnými a propojenými, se odvozuje při buildu z toho, co repozitář už ví. Rozhodnutím je ADR 0152; pravidlem, že diagram se kreslí a nikdy nepíše, je project.a-diagram-is-drawn-not-typed.

Cesta jednoho diagramu

flowchart LR
    fence["a mermaid fence<br/><small>docs, a decision, a rule</small>"]
    data["site/data/generated<br/><small>diagrams.json, plan.json</small>"]
    zola["Zola<br/><small>pre class=mermaid</small>"]
    pass["scripts/lib/diagrams.mjs<br/><small>name, nodes, toolbar, links</small>"]
    check["scripts/ci/link-check<br/><small>every link and every address</small>"]
    viewer["site/diagrams.js<br/><small>draw, zoom, pan, trace, address</small>"]
    fence --> zola
    data --> zola
    zola --> pass
    data -- "identities and routes" --> pass
    pass --> check
    pass --> viewer

Nic v té cestě se nepíše dvakrát. Plot je jediné místo, kde je vztah zapsán; identity, na které může uzel odkazovat, jsou ty, které scripts/generate-site-data již zapsal; a prohlížeč čte to, co build připravil, ne vlastní konfiguraci.

Co build přidává k diagramu

scripts/site-build spouští scripts/lib/diagrams.mjs nad stránkami, které napsala Zola. Pro každé <pre class="mermaid"> přidává čtyři věci:

Stránka, která by nesla dva diagramy pod jedním deklarovaným jménem, se odmítne a sestavení se zastaví (exit 10). Zdroj diagramu se nikdy nemění.

Odkazy se odvozují

Uzel se stane odkazem, když jeho id, jeho štítek nebo jeden řádek jeho štítku je identitou objektu, pro který tento build napsal stránku:

Identita uvnitř delšího popisku se rozřeší také, ale jen když popisek jmenuje jeden objekt. Popisek, který jmenuje dva, nebo objekt, pro který tento web nemá stránku, se neodkazuje na žádný: odkaz, který by vybral ten, jejž dokáže rozřešit, by byl hádáním. Holý název souboru ve větě není identita. Identita, jejíž stránku build nezapsal, se nenabízí vůbec.

Nikdo nezapisuje href do diagramu. Direktiva click v Mermaidu se nepoužívá: odkaz existuje, protože se v diagramu objevuje identita, a při dalším sestavení zmizí, když zmizí objekt.

Prohlížeč

site/diagrams.js načítají jen stránky, které nesou diagram, a stahuje vendorovaný build Mermaid poté, co byla stránka zpracována. Každý diagram kreslí ve vlastních barvách stránky, čtených z design tokenů, a při změně motivu je vykreslí znovu.

Diagram příliš velký na přečtení vcelku, například graf závislostí všech úkolů, se otevře v čitelné velikosti z levého horního rohu a odtud se posouvá. Obyčejné kolečko vždy posouvá stránku.

Rámec je vlastní <pre> diagramu: zachovává své id a místo v pořadí tabulátoru. Diagram, který se nepodaří nakreslit, ponechá svůj zdroj viditelný, nedostane žádné ovládací prvky a ohlásí chybu v konzoli prohlížeče, kterou scripts/interaction-probe považuje za nález.

Adresy

scripts/ci/link-check rozhoduje obojí offline. První je běžný fragment: id musí na stránce existovat. Druhý se vyřeší, jen když stránka nese diagram a diagram deklaruje uzel, takže odkaz na uzel, který byl přejmenován, shodí build, který jej přejmenoval.

Grafy

Graf je tabulka, kterou stránka už vykresluje, deklarovaná jako taková:

<figure id="chart-milestones" data-chart="bar" data-chart-stack data-chart-horizontal data-chart-unit="issues">
  <table>
    <thead><tr><th>milestone</th><th data-series="done">…</th></tr></thead>
    <tbody><tr id="chart-milestones:m000"><td><a href="…">M000</a></td><td>15</td></tr></tbody>
  </table>
</figure>

site/charts.js vykreslí tabulku pomocí Apache ECharts: první sloupec je kategorie a každý sloupec, jehož záhlaví nese data-series, je řada. Čísla se čtou z buněk, které stránka ukazuje, takže graf nemůže být v rozporu se svou tabulkou a neexistuje druhá kopie dat. Tabulka na stránce zůstává; dostane ji čtenář bez JavaScriptu, čtečka obrazovky i tisk.

Řada dostane barvu, v níž je kreslena její hlavička, když hlavička nese odznak stavu, takže stav se kreslí v barvě, kterou pro něj design deklaruje; jakákoli jiná řada dostane další z barev řad designu. ECharts se vendoruje při sestavení z připnutého balíčku npm a stáhne se poprvé, když se graf přiblíží k viewportu.

Takto se dnes kreslí dva grafy:

Co se kontroluje a čím

Grafy zatím nemají specifikaci chování: nedeklarují žádný ovládací prvek, takže sonda nemá co tvrdit a to, co graf čte ze své tabulky, nepotvrzuje žádná kontrola. To je úkol I2654.

Omezení

• Odkazy na uzly a adresy uzlů existují pro vývojové diagramy a stavové diagramy. Sekvenční diagram nebo jakýkoli jiný druh se pojmenuje, kreslí, zvětšuje a adresuje jako celek a nemá uzly, na které by se odkazovalo.
• Hrany se trasují jen ve vývojových diagramech.
• Domovská stránka nenese žádný diagram ani graf. Její sekce a rozpočet bajtů jsou deklarovány v site/data/homepage.toml a přidání kteréhokoli je změnou této deklarace (úkol I2655).
• Cockpit a majordomus ui kreslí vlastní grafy a tento prohlížeč nepoužívají (úkol I2656).