feat(ui5-timeline): introduce header and info-bar slots (#13548)

## High-level Architecture additions

- Added a `header` slot for a controls bar above the items.
- Added an `infoBar` slot for a status bar below the controls, reflecting the active state.
- Added a `stickyHeader` boolean that pins the header bar to the top while scrolling.

## Overview

The Timeline had no built-in way to place controls (search, filter, sort) above its items. Applications had to build custom layouts around it, leading to inconsistent patterns and no standardized sticky behavior.

## What we did

Added two optional slots above the items area:

- **`header`** — for controls (search field, sort/filter buttons). Typically holds a `ui5-toolbar`.
- **`infoBar`** — for status display (active filter tokens, item count). Typically holds a `ui5-bar`.

Plus:

| Property | What it does |
|----------|-------------|
| `stickyHeader` | Pins both bars at the top while scrolling |

## Key points

- The Timeline does **not** search, sort, or filter — apps stay in full control.
- Sticky behavior is **CSS-only** — no JS measurement needed.
- Fully **backwards compatible** — Timelines without these slots work as before.

Author: hinzzx

packages/fiori/cypress/specs/Timeline.cy.tsx

@@ -581,4 +581,114 @@ describe("TimelineItem iconTooltip", () => {
 	});
 });
 
+describe("Timeline header and info-bar slots", () => {
+	it("renders the header slot when content is provided", () => {
+		cy.mount(
+			<Timeline>
+				<div slot="header" id="header-content" data-testid="header">Controls</div>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-header")
+			.should("exist");
+
+		cy.get("#header-content").should("be.visible");
+	});
+
+	it("renders the info-bar slot when content is provided", () => {
+		cy.mount(
+			<Timeline>
+				<div slot="infoBar" id="info-bar-content">Active filters: 2</div>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-info-bar")
+			.should("exist");
+
+		cy.get("#info-bar-content").should("be.visible");
+	});
+
+	it("does not render header or info-bar wrappers when slots are empty", () => {
+		cy.mount(
+			<Timeline>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-header")
+			.should("not.exist");
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-info-bar")
+			.should("not.exist");
+	});
+
+	it("renders both slots side by side when both are provided", () => {
+		cy.mount(
+			<Timeline>
+				<div slot="header" id="hdr">Search/Filter/Sort</div>
+				<div slot="infoBar" id="ifb">Status: 3 items</div>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-header")
+			.should("exist");
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-info-bar")
+			.should("exist");
+
+		cy.get("#hdr").should("be.visible");
+		cy.get("#ifb").should("be.visible");
+	});
+
+	it("reflects stickyHeader as the [sticky-header] host attribute and pins the whole header area", () => {
+		cy.mount(
+			<Timeline stickyHeader={true}>
+				<div slot="header" id="hdr">Header</div>
+				<div slot="infoBar" id="ifb">Info</div>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.should("have.attr", "sticky-header");
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-header-area")
+			.should("have.css", "position", "sticky");
+	});
+
+	it("does not apply sticky positioning when stickyHeader is false (default)", () => {
+		cy.mount(
+			<Timeline>
+				<div slot="header" id="hdr">Header</div>
+				<div slot="infoBar" id="ifb">Info</div>
+				<TimelineItem titleText="Item" subtitleText="now" icon={calendar}></TimelineItem>
+			</Timeline>
+		);
+
+		cy.get("[ui5-timeline]")
+			.should("not.have.attr", "sticky-header");
+
+		cy.get("[ui5-timeline]")
+			.shadow()
+			.find(".ui5-timeline-header-area")
+			.should("not.have.css", "position", "sticky");
+	});
+});
 

packages/fiori/src/Timeline.ts

@@ -1,5 +1,5 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
-import type { DefaultSlot } from "@ui5/webcomponents-base/dist/UI5Element.js";
+import type { DefaultSlot, Slot } from "@ui5/webcomponents-base/dist/UI5Element.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
@@ -70,6 +70,23 @@ const GROWING_WITH_SCROLL_DEBOUNCE_RATE = 250; // ms
  * These entries can be generated by the system (for example, value XY changed from A to B), or added manually.
  * There are two distinct variants of the timeline: basic and social. The basic timeline is read-only,
  * while the social timeline offers a high level of interaction and collaboration, and is integrated within SAP Jam.
+ *
+ * ### Header and Info Bar Slots
+ *
+ * The Timeline exposes two named slots above the items area:
+ *
+ * - `header` — for a controls bar (search field, filter trigger, sort toggle, etc.).
+ * The most common pattern is to place a `ui5-toolbar` containing a search input and buttons that open
+ * a filter dialog or toggle sort direction. The Timeline itself performs no filtering, sorting, or
+ * searching — the application listens for events from its own controls and reorders, hides, or
+ * adds items in the default slot accordingly.
+ *
+ * - `infoBar` — for a status bar that reflects the result of the controls (active filters,
+ * applied sort, current search query). Typically contains tokens, labels, or a `ui5-bar`.
+ *
+ * The Timeline itself does not filter, sort, or search — the application owns that logic.
+ * Use `stickyHeader` to pin both bars while the Timeline's items scroll. Give the Timeline
+ * a constrained height in this mode so it owns its scrollbar.
  * @constructor
  * @extends UI5Element
  * @public
@@ -153,6 +170,22 @@ class Timeline extends UI5Element {
 	@property()
 	growing: `${TimelineGrowingMode}` = "None";
 
+	/**
+	 * Defines whether the content of the `header` and `infoBar` slots remains visible when the user scrolls the Timeline.
+	 *
+	 * **Note:** The bars pin to the Timeline's own scrollport. Give the Timeline a
+	 * constrained height (for example `style="height: 32rem"`) so its items scroll
+	 * inside it. Placing the Timeline inside an externally scrolling ancestor while
+	 * leaving the Timeline itself unsized is not supported in this mode — the bars
+	 * will scroll away with the ancestor.
+	 *
+	 * @default false
+	 * @public
+	 * @since 2.22.0
+	 */
+	@property({ type: Boolean })
+	stickyHeader = false;
+
 	/**
 	 * Defines the active state of the `More` button.
 	 * @private
@@ -167,12 +200,35 @@ class Timeline extends UI5Element {
 	@slot({ type: HTMLElement, individualSlots: true, "default": true })
 	items!: DefaultSlot<ITimelineItem>;
 
+	/**
+	 * Defines the content of the Timeline's header area, displayed above the items.
+	 * Typically a `ui5-toolbar` with search, sort, and filter controls.
+	 *
+	 * @public
+	 * @since 2.22.0
+	 */
+	@slot()
+	header!: Slot<HTMLElement>;
+
+	/**
+	 * Defines the content of the Timeline's info bar area, displayed below the header
+	 * and above the items. Use for status display (applied filters, sort direction, counts).
+	 *
+	 * @public
+	 * @since 2.22.0
+	 */
+	@slot()
+	infoBar!: Slot<HTMLElement>;
+
 	@query(".ui5-timeline-end-marker")
 	timelineEndMarker!: HTMLElement;
 
 	@query((`[id="ui5-timeline-growing-btn"]`))
 	growingButton!: HTMLElement;
 
+	@query(".ui5-timeline-scroll-container")
+	_scrollContainer!: HTMLElement;
+
 	@i18n("@ui5/webcomponents-fiori")
 	static i18nBundle: I18nBundle;
 
@@ -195,6 +251,14 @@ class Timeline extends UI5Element {
 			: Timeline.i18nBundle.getText(TIMELINE_ARIA_LABEL);
 	}
 
+	get _hasHeader(): boolean {
+		return this.header.length > 0;
+	}
+
+	get _hasInfoBar(): boolean {
+		return this.infoBar.length > 0;
+	}
+
 	get showBusyIndicatorOverlay() {
 		return !this.growsWithButton && this.loading;
 	}
@@ -308,6 +372,27 @@ class Timeline extends UI5Element {
 		this._itemNavigation.setCurrentItem(target);
 	}
 
+	_onwheel(e: WheelEvent) {
+		// In horizontal layout, translate vertical wheel into horizontal scroll
+		// so a regular mouse wheel can scroll through items.
+		if (this.layout !== TimelineLayout.Horizontal || !e.deltaY || e.deltaX) {
+			return;
+		}
+
+		const container = this._scrollContainer;
+		if (!container) {
+			return;
+		}
+
+		const canScroll = container.scrollWidth > container.clientWidth;
+		if (!canScroll) {
+			return;
+		}
+
+		container.scrollLeft += e.deltaY;
+		e.preventDefault();
+	}
+
 	onBeforeRendering() {
 		this._itemNavigation._navigationMode = this.layout === TimelineLayout.Horizontal ? NavigationMode.Horizontal : NavigationMode.Vertical;
 

packages/fiori/src/TimelineTemplate.tsx

@@ -13,6 +13,7 @@ export default function TimelineTemplate(this: Timeline) {
 			aria-label={this.ariaLabel}
 			onFocusIn={this._onfocusin}
 			onKeyDown={this._onkeydown}
+			onWheel={this._onwheel}
 		>
 			<BusyIndicator
 				id={`${this._id}-busyIndicator`}
@@ -21,7 +22,20 @@ export default function TimelineTemplate(this: Timeline) {
 				class="ui5-timeline-busy-indicator"
 			>
 				<div class="ui5-timeline-scroll-container">
-
+					{(this._hasHeader || this._hasInfoBar) &&
+						<div class="ui5-timeline-header-area">
+							{this._hasHeader &&
+								<div class="ui5-timeline-header">
+									<slot name="header"></slot>
+								</div>
+							}
+							{this._hasInfoBar &&
+								<div class="ui5-timeline-info-bar">
+									<slot name="infoBar"></slot>
+								</div>
+							}
+						</div>
+					}
 					<div class="ui5-timeline-list"
 						role={listRole}
 						aria-live="polite"

packages/fiori/src/themes/Timeline.css

@@ -59,12 +59,25 @@
 	margin-inline-start: var(--_ui5_tl_li_margin_bottom);
 }
 
+/* Scroll container */
 :host([layout="Horizontal"]) .ui5-timeline-scroll-container {
-	overflow: auto;
+	overflow-x: auto;
+	overflow-y: hidden;
 	/* The padding values of the parent container are added to the size of scroll container */
 	width: calc(100% + var(--_ui5_timeline_scroll_container_offset));
 }
 
+:host([layout="Vertical"]) .ui5-timeline-scroll-container {
+	height: 100%;
+	width: 100%;
+	overflow: auto;
+}
+
+.ui5-timeline-scroll-container {
+	display: flex;
+	flex-direction: column;
+}
+
 :host([loading]) .ui5-timeline-growing-button-busy-indicator:not([_is-busy]) {
 	display: none;
 }
@@ -77,12 +90,28 @@
 	box-sizing: border-box;
 }
 
-:host([layout="Vertical"]) .ui5-timeline-scroll-container {
-	height: 100%;
-	width: 100%;
-}
-
 :host([growing="Scroll"]) .ui5-timeline-end-marker {
 	/* Ensure the list-end-marker has a block property to always be stretched and "visible" on the screen */
 	display: inline-block;
-}
+}
+
+/* Header area — wraps header + info-bar slots above the items */
+.ui5-timeline-header-area {
+	flex-shrink: 0;
+	width: 100%;
+	background: var(--sapBackgroundColor);
+	margin-block-end: 1rem;
+}
+
+.ui5-timeline-header,
+.ui5-timeline-info-bar {
+	flex-shrink: 0;
+}
+
+/* Sticky header — pins to the top in vertical layout and to the inline-start in horizontal layout */
+:host([sticky-header]) .ui5-timeline-header-area {
+	position: sticky;
+	top: 0;
+	inset-inline-start: 0;
+	z-index: 2;
+}