GrTimeline

A heterogeneous feed is written as items: GrTimelineItem one after another. A uniform set is handed over with a prop — and only then does the feed know the composition of the data, that is, it can group it:

<GrTimeline :items="events" item-key="id" group-by="day">
  <template #group="{ group, items }">{{ group }} · {{ items.length }}</template>
  <template #item="{ item }">
    <GrTimelineItem :time="item.at" :title="item.title" :tone="item.tone" />
  </template>
</GrTimeline>

groupBy only cuts the set into groups: the order of the events and the order of the groups stay as they arrived. There is no sorting and no parsing of dates inside — otherwise the component would get time zones and local formats, which the library does not have. What counts as a day is decided by the application: with a string in a field or with a function.

A flat feed is an <ol>: the events are ordered in time, and a screen reader is obliged to announce that. A group is a <section> with an <h3> heading (the level is set by groupHeadingLevel) and an <ol> of its own inside. The heading of a day is not made a list item: an <li> with a date would enter the set of events and would be announced as one of them.

The axis and the markers are decorative (aria-hidden) — the meaning is carried by the text of the event. The tone of a marker says nothing beyond what is written in words: colour here reinforces rather than replaces.

The timestamp is a <time>; with datetime it is machine-readable as well.

orientation="horizontal" turns the axis left to right, the events become columns, and the feed becomes a scroller (and gets tabindex="0": a scrolling block has to be reachable from the keyboard). The vertical layouts do not apply in it — a horizontal axis has neither a column of time nor sides — and in DEV the component warns about that.

alternate collapses into a one-sided feed on a narrow screen: a two-sided feed at 320px is unreadable, and leaving that to the consumer would mean leaving them a bug.

time behaves differently in a narrow column: the column of time stays at every width — the layout is taken for its sake — and it is the column of content that shrinks. Its width is set by the --gr-timeline-time-width hook (5.5rem by default), and in a really tight place it is worth reducing.

Truncating a long text is the consumer’s business: put a truncate (or a text-overflow of your own) on the heading. The feed can shrink for that: its flexible tracks are declared minmax(0, 1fr) rather than a bare 1fr. The difference is not obvious and deserves an explanation: 1fr is minmax(auto, 1fr), the minimum of such a track equals the min-content of the content, and with the white-space: nowrap of truncate that is the full width of the line. The track would spread to fit the text, there would be nothing to truncate, and the line would carry itself beyond the edge — that is, truncate would not work by construction.

The side of an item in alternate is an nth-child, and the end of the axis at the last event is a last-child. An item does not know its index and must not know it: registering the children in a context on onMounted would give an order dependent on the order of mounting and would fall apart on a v-if in the middle of the feed.

Hence the shape of the markup as well: the <li> is drawn by GrTimelineItem itself — in both modes, and in the data mode it stands inside the #item slot. The axis is a segment at every item rather than one long line: neighbouring segments join by themselves, and there is no need to measure the height of the list.

tone colours the dot with a tone role, variant="outlined" makes it hollow, and the #marker slot replaces the dot with anything at all — a status icon, the avatar of an author, the number of a step.

pending means the event has not happened yet: the dot is hollow, and the axis runs dashed starting from the segment leading to it — that is, both it and the item’s own segment are dashed. The dashing starts precisely from the leading one rather than from the following one: an unfinished event is usually the last, and its own segment is not visible at all — the dashing would turn out invisible in exactly the most frequent case.

If empty is not set, the feed decides for itself: in the data mode by the length of items, in the slot mode by whether there are meaningful nodes in the slot. The check does not come down to “the slot is not empty”: a v-for over an empty array leaves a fragment with no nodes, and a v-if leaves a comment, and neither of those is an item of the feed. Without that a feed with a v-for over empty data would draw an axis out of nothing instead of an explanation.

The prop overrides the automatic detection in both directions — it is needed where “empty” is decided by the server rather than by the markup. The text is changed with emptyText, and the look as a whole with the #empty slot.

loading shows loadingRows placeholder rows (three by default) built on GrSkeleton rather than a spinner over emptiness: the placeholders hold the height, and the appearance of the data does not shift the page.

• there is no keyboard of its own — the feed shows rather than selects; interactive elements are put inside by the consumer, and the tab order is theirs;
• an item is not clickable by itself — a clickable row is assembled with a nested GrLink/GrButton, as in GrList;
• there is no virtualisation — useVirtualList is designed for a uniform row height, and events are heterogeneous; a thousand events in an interface is pagination rather than a window;
• there is no appearance animation — movement requires a prefers-reduced-motion branch of its own, and the value here is decorative;
• this is not GrSteps — a horizontal feed looks like a stepper but is not made of steps: neither aria-current, nor navigation, nor validation per step.