Skip to content

Commit d906d03

Browse files
hinzzxhinzzx
committed
add clearer docs
1 parent bce70b7 commit d906d03

5 files changed

Lines changed: 78 additions & 75 deletions

File tree

‎packages/fiori/src/Timeline.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,8 @@ const GROWING_WITH_SCROLL_DEBOUNCE_RATE = 250; // ms
8585
* applied sort, current search query). Typically contains tokens, labels, or a `ui5-bar`.
8686
*
8787
* The Timeline itself does not filter, sort, or search — the application owns that logic.
88-
* Use `stickyHeader` to pin both bars while scrolling.
88+
* Use `stickyHeader` to pin both bars while the Timeline's items scroll. Give the Timeline
89+
* a constrained height in this mode so it owns its scrollbar.
8990
* @constructor
9091
* @extends UI5Element
9192
* @public
@@ -172,6 +173,12 @@ class Timeline extends UI5Element {
172173
/**
173174
* Defines whether the content of the `header` and `infoBar` slots remains visible when the user scrolls the Timeline.
174175
*
176+
* **Note:** The bars pin to the Timeline's own scrollport. Give the Timeline a
177+
* constrained height (for example `style="height: 32rem"`) so its items scroll
178+
* inside it. Placing the Timeline inside an externally scrolling ancestor while
179+
* leaving the Timeline itself unsized is not supported in this mode — the bars
180+
* will scroll away with the ancestor.
181+
*
175182
* @default false
176183
* @public
177184
* @since 2.22.0

‎packages/fiori/test/pages/TimelineHeaderInfoBar.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -200,14 +200,14 @@ <h2>2. Minimal — search only with live count</h2>
200200
</div>
201201
</article>
202202

203-
<!-- Scenario 3: ancestor owns the scroll → sticky header still pins to it -->
203+
<!-- Scenario 3: ancestor owns the scroll → bars scroll with the content -->
204204
<article class="scenario">
205205
<div class="scenario-header">
206206
<h2>3. Ancestor scroll container</h2>
207-
<p>The ancestor (dashed border) owns scrolling. The Timeline expands to its content and <code>stickyHeader</code> pins the header area to the ancestor's scrollport — common when a Timeline is embedded in a <code>DynamicPage</code>.</p>
207+
<p>The ancestor (dashed border) owns scrolling. The Timeline expands to its content and the <code>header</code> and <code>infoBar</code> slots scroll together with the items. <code>stickyHeader</code> is not used here — it pins to the Timeline's own scrollport, so it requires a Timeline that owns its scrollbar (see scenarios 1 and 2).</p>
208208
</div>
209209
<div class="ancestor-scroll">
210-
<ui5-timeline id="ancestorScrollTimeline" sticky-header>
210+
<ui5-timeline id="ancestorScrollTimeline">
211211
<ui5-toolbar slot="header">
212212
<ui5-toolbar-item>
213213
<ui5-label>Header sticks to the ancestor</ui5-label>

‎packages/website/docs/_components_pages/fiori/Timeline/Timeline.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@ The Timeline does not filter, sort, or search — the application owns that logi
5454

5555
<WithFilter/>
5656

57-
#### Sticky in a scrollable page area
57+
#### Sticky in a scrollable Timeline
5858

59-
When the Timeline sits inside an externally scrolling container, `stickyHeader` pins the bars to the top of that ancestor.
59+
When the Timeline owns its scrollbar (give it a constrained height), `stickyHeader` keeps the `header` and `infoBar` slots pinned to the top while the items scroll.
6060

6161
<StickyInPage/>

‎packages/website/docs/_samples/fiori/Timeline/StickyInPage/sample.html‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,32 @@
1111
<body style="background-color: var(--sapBackgroundColor); padding: 2rem;">
1212
<!-- playground-fold-end -->
1313

14-
<div style="height: 18rem; overflow: auto; border: 1px solid var(--sapGroup_ContentBorderColor); border-radius: 0.5rem;">
15-
<ui5-timeline id="approvalTimeline" sticky-header>
16-
<ui5-toolbar slot="header">
17-
<ui5-toolbar-select id="statusFilter">
18-
<ui5-toolbar-select-option selected>All statuses</ui5-toolbar-select-option>
19-
<ui5-toolbar-select-option data-status="Pending">Pending</ui5-toolbar-select-option>
20-
<ui5-toolbar-select-option data-status="Approved">Approved</ui5-toolbar-select-option>
21-
<ui5-toolbar-select-option data-status="Rejected">Rejected</ui5-toolbar-select-option>
22-
</ui5-toolbar-select>
23-
</ui5-toolbar>
14+
<ui5-timeline id="approvalTimeline" sticky-header style="height: 18rem;">
15+
<ui5-toolbar slot="header">
16+
<ui5-toolbar-select id="statusFilter">
17+
<ui5-toolbar-select-option selected>All statuses</ui5-toolbar-select-option>
18+
<ui5-toolbar-select-option data-status="Pending">Pending</ui5-toolbar-select-option>
19+
<ui5-toolbar-select-option data-status="Approved">Approved</ui5-toolbar-select-option>
20+
<ui5-toolbar-select-option data-status="Rejected">Rejected</ui5-toolbar-select-option>
21+
</ui5-toolbar-select>
22+
</ui5-toolbar>
2423

25-
<ui5-bar slot="infoBar" design="Subheader">
26-
<div slot="startContent" id="tokenArea" style="display: flex; align-items: center; gap: 0.5rem; padding: 0.375rem;"></div>
27-
<ui5-label slot="endContent" id="infoLabel">10 documents</ui5-label>
28-
</ui5-bar>
24+
<ui5-bar slot="infoBar" design="Subheader">
25+
<div slot="startContent" id="tokenArea" style="display: flex; align-items: center; gap: 0.5rem; padding: 0.375rem;"></div>
26+
<ui5-label slot="endContent" id="infoLabel">10 documents</ui5-label>
27+
</ui5-bar>
2928

30-
<ui5-timeline-item title-text="Purchase Order #4012 submitted" subtitle-text="10.12.2024 08:45" icon="document-text" name="Anna Weber" data-status="Pending"></ui5-timeline-item>
31-
<ui5-timeline-item title-text="Travel Expense #891 submitted" subtitle-text="10.12.2024 09:10" icon="document-text" name="Tom Berger" data-status="Pending"></ui5-timeline-item>
32-
<ui5-timeline-item title-text="Invoice #7734 approved" subtitle-text="10.12.2024 09:30" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
33-
<ui5-timeline-item title-text="Contract Amendment reviewed" subtitle-text="10.12.2024 10:15" icon="to-be-reviewed" name="Carla Rossi" data-status="Pending"></ui5-timeline-item>
34-
<ui5-timeline-item title-text="Budget Request #220 approved" subtitle-text="10.12.2024 11:02" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
35-
<ui5-timeline-item title-text="Vendor Onboarding rejected" subtitle-text="10.12.2024 11:40" icon="employee-rejections" name="Carla Rossi" data-status="Rejected"></ui5-timeline-item>
36-
<ui5-timeline-item title-text="NDA signed" subtitle-text="10.12.2024 13:05" icon="signature" name="Anna Weber" data-status="Approved"></ui5-timeline-item>
37-
<ui5-timeline-item title-text="Capital Expenditure #55 submitted" subtitle-text="10.12.2024 14:00" icon="document-text" name="Tom Berger" data-status="Pending"></ui5-timeline-item>
38-
<ui5-timeline-item title-text="Service Agreement approved" subtitle-text="10.12.2024 14:30" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
39-
<ui5-timeline-item title-text="Hiring Request #18 rejected" subtitle-text="10.12.2024 15:20" icon="employee-rejections" name="Carla Rossi" data-status="Rejected"></ui5-timeline-item>
40-
</ui5-timeline>
41-
</div>
29+
<ui5-timeline-item title-text="Purchase Order #4012 submitted" subtitle-text="10.12.2024 08:45" icon="document-text" name="Anna Weber" data-status="Pending"></ui5-timeline-item>
30+
<ui5-timeline-item title-text="Travel Expense #891 submitted" subtitle-text="10.12.2024 09:10" icon="document-text" name="Tom Berger" data-status="Pending"></ui5-timeline-item>
31+
<ui5-timeline-item title-text="Invoice #7734 approved" subtitle-text="10.12.2024 09:30" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
32+
<ui5-timeline-item title-text="Contract Amendment reviewed" subtitle-text="10.12.2024 10:15" icon="to-be-reviewed" name="Carla Rossi" data-status="Pending"></ui5-timeline-item>
33+
<ui5-timeline-item title-text="Budget Request #220 approved" subtitle-text="10.12.2024 11:02" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
34+
<ui5-timeline-item title-text="Vendor Onboarding rejected" subtitle-text="10.12.2024 11:40" icon="employee-rejections" name="Carla Rossi" data-status="Rejected"></ui5-timeline-item>
35+
<ui5-timeline-item title-text="NDA signed" subtitle-text="10.12.2024 13:05" icon="signature" name="Anna Weber" data-status="Approved"></ui5-timeline-item>
36+
<ui5-timeline-item title-text="Capital Expenditure #55 submitted" subtitle-text="10.12.2024 14:00" icon="document-text" name="Tom Berger" data-status="Pending"></ui5-timeline-item>
37+
<ui5-timeline-item title-text="Service Agreement approved" subtitle-text="10.12.2024 14:30" icon="employee-approvals" name="Carla Rossi" data-status="Approved"></ui5-timeline-item>
38+
<ui5-timeline-item title-text="Hiring Request #18 rejected" subtitle-text="10.12.2024 15:20" icon="employee-rejections" name="Carla Rossi" data-status="Rejected"></ui5-timeline-item>
39+
</ui5-timeline>
4240

4341
<!-- playground-fold -->
4442
<script type="module" src="main.js"></script>

‎packages/website/docs/_samples/fiori/Timeline/StickyInPage/sample.tsx‎

Lines changed: 41 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -61,51 +61,49 @@ function App() {
6161
}, [activeStatus]);
6262

6363
return (
64-
<div style={{ height: "18rem", overflow: "auto", border: "1px solid var(--sapGroup_ContentBorderColor)", borderRadius: "0.5rem" }}>
65-
<Timeline stickyHeader>
66-
<Toolbar slot="header">
67-
<ToolbarSelect onChange={(e: any) => {
68-
const selected = e.detail?.selectedOption;
69-
setActiveStatus(selected?.getAttribute("data-status") || "");
70-
}}>
71-
{STATUS_OPTIONS.map(status => (
72-
<ToolbarSelectOption
73-
key={status}
74-
data-status={status}
75-
selected={status === activeStatus}
76-
>
77-
{STATUS_LABELS[status]}
78-
</ToolbarSelectOption>
79-
))}
80-
</ToolbarSelect>
81-
</Toolbar>
64+
<Timeline stickyHeader style={{ height: "18rem" }}>
65+
<Toolbar slot="header">
66+
<ToolbarSelect onChange={(e: any) => {
67+
const selected = e.detail?.selectedOption;
68+
setActiveStatus(selected?.getAttribute("data-status") || "");
69+
}}>
70+
{STATUS_OPTIONS.map(status => (
71+
<ToolbarSelectOption
72+
key={status}
73+
data-status={status}
74+
selected={status === activeStatus}
75+
>
76+
{STATUS_LABELS[status]}
77+
</ToolbarSelectOption>
78+
))}
79+
</ToolbarSelect>
80+
</Toolbar>
8281

83-
<Bar slot="infoBar" design="Subheader">
84-
<div slot="startContent" style={{ display: "flex", alignItems: "center", gap: "0.5rem", padding: "0.375rem" }}>
85-
{activeStatus !== "" && (
86-
<Token
87-
text={activeStatus}
88-
forcedTabIndex="0"
89-
selected
90-
onSelect={(e: any) => { e.target.selected = true; }}
91-
onDelete={() => setActiveStatus("")}
92-
/>
93-
)}
94-
</div>
95-
<Label slot="endContent">{`${visibleEntries.length} of ${ENTRIES.length} documents`}</Label>
96-
</Bar>
82+
<Bar slot="infoBar" design="Subheader">
83+
<div slot="startContent" style={{ display: "flex", alignItems: "center", gap: "0.5rem", padding: "0.375rem" }}>
84+
{activeStatus !== "" && (
85+
<Token
86+
text={activeStatus}
87+
forcedTabIndex="0"
88+
selected
89+
onSelect={(e: any) => { e.target.selected = true; }}
90+
onDelete={() => setActiveStatus("")}
91+
/>
92+
)}
93+
</div>
94+
<Label slot="endContent">{`${visibleEntries.length} of ${ENTRIES.length} documents`}</Label>
95+
</Bar>
9796

98-
{visibleEntries.map(entry => (
99-
<TimelineItem
100-
key={entry.id}
101-
titleText={entry.titleText}
102-
subtitleText={entry.subtitleText}
103-
icon={entry.icon}
104-
name={entry.name}
105-
/>
106-
))}
107-
</Timeline>
108-
</div>
97+
{visibleEntries.map(entry => (
98+
<TimelineItem
99+
key={entry.id}
100+
titleText={entry.titleText}
101+
subtitleText={entry.subtitleText}
102+
icon={entry.icon}
103+
name={entry.name}
104+
/>
105+
))}
106+
</Timeline>
109107
);
110108
}
111109

0 commit comments

Comments
 (0)