Timeline

Obsah

• Úvod
• Anatomie
• Varianty
• Responzivita a mobile specifika
• Přístupnost
• Pro vývojáře
• Varování
• Doporučení

Úvod

Účel

Timeline (časová osa) zobrazuje postup nebo proces jako číslovanou posloupnost kroků rozdělenou do kategorií (fází). Kroky mohou probíhat ve dvou souběžných stopách – typicky „Musí“ (povinné kroky) a „Může“ (volitelné kroky) – a dva kroky mohou sdílet jedno pořadí. Boční navigace „Obsah“ ukazuje, ve které fázi se uživatel právě nachází, a umožňuje mezi fázemi přeskakovat.

Kde se používá

Komponenta je vhodná tam, kde uživatel potřebuje pochopit celý průběh vyřízení věci dřív, než začne. Typicky pro:

• postupy vyřízení žádostí (co musím udělat, co můžu udělat, v jakém pořadí),
• návody a metodiky s několika fázemi,
• harmonogramy projektů a připojování systémů (např. připojení AIS k ISZR).

Anatomie

• Začátek a konec (volitelné) – nadpis celého procesu („Podání žádosti“, „Vyřízeno“) se značkou na ose: šipka, tečka, vlastní ikona, nebo bez značky.
• Kategorie (fáze) – nadpis fáze („1. Příprava“) a nad osou volitelně názvy stop („Musí“ / „Může“). Osa fáze může končit šipkou dolů, nahoru, nebo bez šipky.
• Osa – tečkovaná svislá linka, na které leží číslované uzly kroků. Číslování pokračuje napříč kategoriemi.
• Krok – číslovaný uzel a karta (gov-timeline-card) napojená na osu tečkovaným „kolínkem“. Karta obsahuje nadpis s ikonou, štítky (gov-tag), popis a volitelně jednu akci: buď tlačítko (gov-button) ve slotu footer, nebo je klikací celá karta (href) – nikdy obojí.
• Sdílený krok – krok se dvěma kartami (jedna v každé stopě) má jeden uzel s kolínky na obě strany.
• Navigace „Obsah“ – seznam odkazů na začátek, všechny kategorie a konec. Aktuální sekce je zvýrazněná; zvýraznění sleduje posun stránky i posun obsahu, který roluje uvnitř vlastní oblasti (např. obsahová část aplikace s vlastním scrollováním).

Varianty

Výchozí varianta (columns="2"). Kroky leží vlevo a vpravo od osy podle stopy, do které patří; nad osou jsou názvy stop. Sdílený krok má jeden uzel s kartami po obou stranách. Varianta vyžaduje šíři obrazovky alespoň xl (1280 px) a místo pro obě řady karet vedle sebe (časová osa široká zhruba 830 px). Na užších obrazovkách i v užším kontejneru (obsahový sloupec stránky, osa vedle navigace) se osa automaticky sbalí (viz Responzivita).

Pro procesy s jedinou stopou (columns="1"). Všechny karty leží vpravo od osy, nad osou je nejvýše jeden název stopy a karty nemají štítek stopy. Sdílené kroky jednosloupcová varianta nezná – každý krok má vlastní pořadové číslo. Karty jsou na širokých obrazovkách širší a celý blok je vycentrovaný.

S numbered="false" se uzly kroků zobrazí jako malé tečky bez čísel. Vhodné tam, kde na pořadí kroků nezáleží – pořadí pak nehlásí ani čtečka obrazovky.

Responzivita a mobile specifika

Timeline používá standardní breakpointy design systému:

Dvousloupcová osa se sbalí i na širší obrazovce, když se do kontejneru, ve kterém leží, nevejdou obě řady karet vedle sebe – např. v obsahovém sloupci stránky nebo vedle navigace „Obsah“. Potřebná šířka jsou dvě karty po 38 znacích s odsazením od osy plus osa, při výchozí velikosti písma zhruba 830 px (s větším písmem roste). Karty tak nikdy nepřetečou mimo kontejner.

Šířku hlavního sloupce časové osy proto určuje její kontejner, ne obsah: <gov-timeline> vložte do bloku, který mu šířku dává (běžný blok, mřížka, gov-container). V kontejneru, který se smršťuje podle obsahu (řádek flexboxu bez flex: 1, width: fit-content, inline-block), by se její hlavní sloupec zúžil na nulu – takovému obalu dejte šířku, např. width: 100%.

Ve sbalené ose se každý krok zobrazí pod sebou a vpravo od osy. Protože poloha už nerozlišuje stopu, zobrazí se u každé karty její štítek („MUSÍ“ / „MŮŽE“). Ze sdíleného kroku se stanou dva samostatné uzly s čísly „N/1“ a „N/2“.

Přístupnost

• Struktura – časová osa je seznam (role="list"), každá kategorie je jeho položka (role="listitem") s nadpisem (ve výchozím stavu <h2>, úroveň nastavíte atributem headline-tag).
• Kroky pro čtečky obrazovky – čísla v uzlech jsou čistě vizuální (aria-hidden). Čtečka místo nich přečte skrytý text „Krok N:“ přímo v nadpisu karty (u sdíleného kroku „Krok N/1:“ a „Krok N/2:“), takže pořadí zazní spolu s obsahem kroku. Dekorativní prvky osy (linka, kolínka, šipky, značky začátku a konce) jsou před čtečkou skryté. S numbered="false" se pořadí nehlásí vůbec.
• Navigace – odkazy „Obsah“ jsou v landmarku <nav> s přístupným názvem (accessible-nav-label, výchozí „Kategorie časové osy“) – na desktopu kolem seznamu odkazů, na mobilu kolem celého akordeonu, takže landmark je dostupný i se zavřeným akordeonem. Aktuální sekci označuje aria-current="location"; první odkaz je aktuální už v serverově vykresleném markupu.
• Ovládání klávesnicí – po aktivaci odkazu v navigaci se stránka posune na vybranou sekci, fokus se přesune na tuto sekci (tabindex="-1") a aktualizuje se adresa (#kotva) – cesta stránky zůstane zachovaná i na stránce s <base href> (např. v Angularu). Uživatel klávesnice nebo čtečky tak pokračuje od vybrané sekce, ne znovu od navigace.
• Omezení pohybu – při nastavení prefers-reduced-motion: reduce se stránka na sekci přesune bez animace a odkazy v navigaci mění stav bez přechodu.
• Vysoký kontrast (Windows, forced-colors) – prohlížeč v tomto režimu zahodí barvy pozadí, proto uzly kroků dostanou obrys, tečkovaná osa, spojnice a značky začátku a konce se kreslí systémovou barvou textu a aktuální odkaz v navigaci je zvýrazněný systémovou barvou výběru.
• Interaktivní karty – karta je klikací buď celá (href), nebo obsahuje akci ve slotu footer. Klikací karta nikdy neobsahuje další interaktivní prvek (odkaz, tlačítko, gov-button, gov-link, pole formuláře…). Pokud ho obsahuje, komponenta to oznámí varováním (viz Varování).

Pro vývojáře

Timeline tvoří čtyři webové komponenty: gov-timeline (osa, navigace), gov-timeline-category (kategorie, začátek a konec), gov-timeline-step (krok s jedním uzlem) a gov-timeline-card (karta kroku). Číslování, pozice v mřížce i odkazy v navigaci komponenta odvozuje z markupu, nic z toho nepíšete ručně.

Styly ​

Komponenta je stylovaná globálně ze styles.css / components.css balíčku @gov-design-system-ce/styles, žádný další stylopis (ani templates.css) nepotřebuje.

Vnější odsazení si komponenta nenastavuje, patří layoutu stránky (např. gov-container). Číslo kroku obklopuje prstenec v barvě pozadí, který zakrývá tečkovanou osu. Výchozí barva je --background-page. Když timeline leží na jiném pozadí (bílá sekce, karta, tmavý panel), nastavte na ni nebo na předka custom property --gov-timeline-surface na barvu tohoto pozadí:

.my-section {
	--gov-timeline-surface: var(--background-block-primary);
}

Použití ​

<gov-timeline columns="2">
  <!-- Začátek procesu -->
  <gov-timeline-category cap="start" headline="Podání žádosti" marker="arrow"></gov-timeline-category>

  <gov-timeline-category headline="1. Příprava" nav-label="Příprava" label-left="Musí" label-right="Může">
    <!-- Krok s jednou kartou (strana podle atributu side kroku) -->
    <gov-timeline-step side="left">
      <gov-timeline-card headline="Podat žádost o připojení">
        <gov-icon slot="icon" type="complex" name="cactus" aria-hidden="true"></gov-icon>
        <div class="gov-timeline-item__tags">
          <gov-tag color="secondary" type="subtle" size="xs">povinné</gov-tag>
        </div>
        <p class="gov-timeline-item__annotation">Vyplňte formulář žádosti.</p>
        <gov-button slot="footer" color="primary" type="solid" size="s" href="#">Otevřít formulář</gov-button>
      </gov-timeline-card>
    </gov-timeline-step>

    <!-- Sdílený krok: dvě karty, první vlevo, druhá vpravo, jeden uzel -->
    <gov-timeline-step>
      <gov-timeline-card headline="Zaplatit správní poplatek"></gov-timeline-card>
      <gov-timeline-card headline="Zvolit elektronickou platbu" href="/platba"></gov-timeline-card>
    </gov-timeline-step>
  </gov-timeline-category>

  <!-- Konec procesu -->
  <gov-timeline-category cap="end" headline="Vyřízeno"></gov-timeline-category>
</gov-timeline>

• Krok (gov-timeline-step) obsahuje jednu nebo dvě gov-timeline-card. Jedna karta leží na straně dané atributem side kroku (jen ve dvousloupcové ose). Dvě karty leží vždy první vlevo a druhá vpravo a sdílejí jeden uzel „N“. Po sbalení osy se uzel rozdělí na „N/1“ a „N/2“. Třetí a další karta kroku se nezobrazí a komponenta to ohlásí varováním.
• Číslování je průběžné napříč kategoriemi. Začátek a konec (kategorie s cap) se nečíslují a nesmí obsahovat kroky (kroky v nich se nevykreslí a komponenta to ohlásí varováním).
• Začátek a konec jsou kategorie s cap="start" nebo cap="end" a značkou marker (dot, arrow, icon, none). Pro marker="icon" vložte ikonu do slotu marker, např. <gov-icon slot="marker" type="components" name="…"></gov-icon>.
• Štítky stop z label-left / label-right kategorie jsou nad osou. Jakmile se dvousloupcová osa sbalí, zobrazí se jako štítek na každé kartě příslušné strany. V columns="1" se na kartách nepoužijí.
• Navigace se sestaví z nadpisů kategorií (odkaz používá nav-label, pokud je zadaný). Kategorie, začátek nebo konec bez headline (a bez nav-label) odkaz v navigaci nedostane. Kategorii bez id komponenta id vygeneruje (unikátní na stránce, nikdy se neopakuje ani po přidání, odebrání či přesunu kategorií), vlastní id zůstane zachované. Vygenerované id ale závisí na stránce a pořadí kategorií, proto pro stálé odkazy na sekci (/stranka#priprava) zadejte kategoriím vlastní id – v Reactu prop id komponenty GovTimelineCategory.

gov-timeline ​

gov-timeline-category ​

gov-timeline-step ​

gov-timeline-card ​

Varování ​

Chybné použití komponenta hlásí přes govWarningLog: neplatná hodnota atributu, třetí karta v kroku, kroky uvnitř začátku nebo konce a interaktivní prvek uvnitř klikací karty. Varování se vypisují do konzole, jen když je zapnuté warningLog v GOV_DS_CONFIG (viz Začínáme pro vývojáře).

Práce s DOM, SSR a frameworky ​

• Přidání a odebrání potomků dělejte přes appendChild, insertBefore a removeChild. Ty komponenty na hostitelských prvcích přesměrují na správné místo, takže fungují i React, Vue a Angular. append, prepend, replaceChild a insertAdjacent* na hostitelích přesměrované nejsou, proto je pro ruční práci s DOM nepoužívejte.
• SSR přes Stencil hydrate: při serverovém vykreslení balíčkem hydrate (renderToString) je markup (osa, uzly, navigace) hotový už ze serveru a první odkaz navigace má aria-current. Sledování scrollu a přesun fokusu se spustí až v prohlížeči.
• React: GovTimeline, GovTimelineCategory, GovTimelineStep a GovTimelineCard z @gov-design-system-ce/react jen vykreslují webové komponenty, takže je nutné jednou zavolat defineCustomElements() (viz README balíčku core-react). ref na GovTimeline je prvek (ref.current.refresh()) a událost gov-change časové osy přichází jako onGovChange. Wrappery předávají prvku i id, style, aria-* a data-*.
• React SSR (Next.js apod.): server vykreslí jen prvky gov-timeline* s atributy a potomky – osu, uzly a navigaci doplní až webová komponenta v prohlížeči. defineCustomElements() proto volejte až po hydrataci, např. v useEffect kořenové komponenty. Kdyby se webové komponenty zaregistrovaly dřív, upravily by DOM ještě před hydratací Reactu a ta by skončila chybou nesouladu (hydration mismatch).
• Vue a Angular: proxy komponenty se generují z webových komponent (GovTimeline, GovTimelineCategory, GovTimelineStep, GovTimelineCard), atributy se zapisují stejně jako u ostatních komponent a událost se odebírá přes @gov-change (Vue) nebo (gov-change) (Angular).
• Odkazy v navigaci po kliknutí zapíší hash do adresy přes history.pushState, který nevyvolá hashchange – router s hash strategií (např. Angular HashLocationStrategy) o změně neví. Kliknutí s Ctrl/Cmd/Shift (otevření v novém panelu či okně) komponenta nechává prohlížeči.
• Vlastní obalové prvky: kategorie, krok i karta mohou ležet uvnitř vlastního prvku (hostitel Angular komponenty, <x-faze>) – komponenta je přiřadí nejbližšímu nadřazenému prvku rodiny Timeline. Obalový prvek ale nesmí vytvářet vlastní box, jinak rozbije mřížku osy: dejte mu display: contents (v Angularu :host { display: contents; }). Obalená kategorie je posledním potomkem svého obalu, proto pod ní odpadne mezera mezi kategoriemi (--spacing-s).

Doporučení

Fáze pojmenujte podle toho, co v nich uživatel dělá ​

Nadpisy kategorií číslujte („1. Příprava“) a v navigaci použijte kratší název bez čísla („Příprava“). Uživatel tak z navigace hned pozná, kde v procesu je.

Stopy používejte jen tehdy, když se kroky skutečně liší ​

Dvousloupcovou variantu použijte, pokud proces obsahuje povinné i volitelné kroky (nebo jinak odlišené souběžné stopy). Pokud mají všechny kroky stejnou váhu, zvolte jednosloupcovou variantu.

Jeden krok, jedna akce ​

Karta kroku má mít nejvýše jednu akci – tlačítko (např. „Otevřít formulář“), nebo odkaz na celé kartě. Více akcí patří až na cílovou stránku kroku.

Udržujte karty krátké ​

Nadpis kroku by měl být krátké sloveso s předmětem („Podat žádost o připojení“), popis maximálně dvě věty. Podrobnosti patří na detail kroku.

Další doporučení ​

• Štítky (gov-tag) používejte pro stav nebo typ kroku („povinné“, „nepovinné“), ne pro dlouhý text.
• id sekcí musí být na stránce unikátní – při více časových osách na jedné stránce jim dejte prefix.
• Dlouhé procesy rozdělte do více kategorií; navigace „Obsah“ pak lépe slouží k orientaci.