Skip to content

Commit 85c6c73

Browse files
plamenivanov91plamenivanov91
authored
docs(ui5-avatar): update Avatar component and documentation (#13136)
## Changes ### Documentation Update - Updated Avatar badge slot JSDoc to recommend (not require) interactive mode - Added note: "Badges are recommended on interactive avatars for better UX and accessibility" - Maintains backwards compatibility - badges work on non-interactive avatars as fallback ### Sample Updates - **WithBadge sample**: Updated all avatars to use `mode="Interactive"` - **AvatarBadge samples**: Updated Basic and ValueStates samples to use `mode="Interactive"` - **Interactive sample**: Uses `mode="Interactive"` API (deprecated `interactive` attr noted) ### New Variant Sample - Created comprehensive "Variants" sample showcasing all Avatar use cases: - Non-interactive avatars (decorative) - Interactive avatars - Interactive avatars with badges (recommended) - Interactive avatars with popup menus - Decorative avatars (hidden from screen readers) - Includes accessibility annotations for each variant - Updated Avatar.mdx to include new Variants section after "With Badge" ## Related Issue Addresses BLI: [ui5-avatar] Samples update - reflects updated screen reader annotations and design specifications ## Notes - All changes follow Conventional Commits specification - No breaking changes - fully backwards compatible - Samples now properly demonstrate recommended usage patterns
1 parent c4d409b commit 85c6c73

8 files changed

Lines changed: 158 additions & 11 deletions

File tree

‎packages/main/src/Avatar.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,10 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
264264
/**
265265
* Defines the optional badge that will be used for visual affordance.
266266
*
267+
* **Recommendation:** While badges are supported on all avatars, it is recommended
268+
* to use them with interactive avatars (via `mode="Interactive"` or `interactive` attribute)
269+
* to provide better user experience and accessibility.
270+
*
267271
* **Note:** While the slot allows for custom badges, to achieve
268272
* the Fiori design, use the `ui5-avatar-badge` component.
269273
* @public

‎packages/website/docs/_components_pages/main/Avatar/Avatar.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ slug: ../Avatar
55
import Basic from "../../../_samples/main/Avatar/Basic/Basic.md";
66
import Interactive from "../../../_samples/main/Avatar/Interactive/Interactive.md";
77
import Decorative from "../../../_samples/main/Avatar/Decorative/Decorative.md";
8+
import Variants from "../../../_samples/main/Avatar/Variants/Variants.md";
89
import WithBadge from "../../../_samples/main/Avatar/WithBadge/WithBadge.md";
910
import ColorSchemes from "../../../_samples/main/Avatar/ColorSchemes/ColorSchemes.md";
1011
import Sizes from "../../../_samples/main/Avatar/Sizes/Sizes.md";
@@ -62,10 +63,15 @@ The Avatar can show images.
6263
<WithImage />
6364

6465
### With Badge
65-
The Avatar supports visual affordance through badges using the `ui5-avatar-badge` component. Badges can display icons with different value states to indicate status or notifications.
66+
The Avatar supports visual affordance through badges using the `ui5-avatar-badge` component. Badges can display icons with different value states to indicate status or notifications. **It is recommended to use badges with interactive avatars** for better user experience and accessibility.
6667

6768
<WithBadge />
6869

70+
### All Variants
71+
A comprehensive overview of all Avatar variants with their recommended use cases and accessibility annotations:
72+
73+
<Variants />
74+
6975
### Custom Styling
7076
The Avatar allows customization with pure CSS on tag level.
7177

‎packages/website/docs/_samples/main/Avatar/Variants/Variants.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import html from '!!raw-loader!./sample.html';
2+
import js from '!!raw-loader!./main.js';
3+
4+
<Editor html={html} js={js} />

‎packages/website/docs/_samples/main/Avatar/Variants/main.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import "@ui5/webcomponents/dist/Avatar.js";
2+
import "@ui5/webcomponents/dist/AvatarBadge.js";
3+
import "@ui5/webcomponents-icons/dist/edit.js";
4+
5+
const interactiveAvatar = document.getElementById("interactive-avt");
6+
const popupAvatar = document.getElementById("popup-avt");
7+
8+
// Interactive avatar click handler
9+
interactiveAvatar.addEventListener("click", () => {
10+
console.log("Interactive avatar clicked");
11+
});
12+
13+
// Avatar with popup click handler
14+
popupAvatar.addEventListener("click", () => {
15+
console.log("Avatar with popup clicked - menu would open here");
16+
});

‎packages/website/docs/_samples/main/Avatar/Variants/sample.html‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<!-- playground-fold -->
2+
<!DOCTYPE html>
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="UTF-8">
7+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
8+
<title>Sample</title>
9+
<style>
10+
.avatar-container {
11+
display: flex;
12+
flex-direction: column;
13+
gap: 2rem;
14+
padding: 1rem;
15+
}
16+
17+
.variant-group {
18+
display: flex;
19+
align-items: center;
20+
gap: 1rem;
21+
}
22+
23+
.variant-description {
24+
display: flex;
25+
flex-direction: column;
26+
gap: 0.25rem;
27+
}
28+
29+
.variant-title {
30+
font-weight: bold;
31+
font-size: 0.875rem;
32+
}
33+
34+
.variant-note {
35+
font-size: 0.75rem;
36+
color: var(--sapTextColor-Muted);
37+
}
38+
</style>
39+
</head>
40+
41+
<body style="background-color: var(--sapBackgroundColor);">
42+
<!-- playground-fold-end -->
43+
44+
<div class="avatar-container">
45+
<!-- Non-interactive Avatar -->
46+
<div class="variant-group">
47+
<ui5-avatar size="M" initials="AB" color-scheme="Accent1"></ui5-avatar>
48+
<div class="variant-description">
49+
<div class="variant-title">Non-interactive Avatar</div>
50+
<div class="variant-note">Decorative with initials - no interaction</div>
51+
</div>
52+
</div>
53+
54+
<!-- Non-interactive with Image -->
55+
<div class="variant-group">
56+
<ui5-avatar size="M">
57+
<img src="../assets/images/avatars/woman_avatar_1.png" alt="Woman Avatar" />
58+
</ui5-avatar>
59+
<div class="variant-description">
60+
<div class="variant-title">Non-interactive Avatar with Image</div>
61+
<div class="variant-note">Image-based avatar - no interaction</div>
62+
</div>
63+
</div>
64+
65+
<!-- Interactive Avatar -->
66+
<div class="variant-group">
67+
<ui5-avatar id="interactive-avt" size="M" mode="Interactive" initials="CD" color-scheme="Accent3"></ui5-avatar>
68+
<div class="variant-description">
69+
<div class="variant-title">Interactive Avatar</div>
70+
<div class="variant-note">Clickable - supports user interaction and callbacks</div>
71+
</div>
72+
</div>
73+
74+
<!-- Interactive Avatar with Badge -->
75+
<div class="variant-group">
76+
<ui5-avatar size="M" mode="Interactive" initials="EF" color-scheme="Accent5">
77+
<ui5-avatar-badge icon="edit" state="None" slot="badge"></ui5-avatar-badge>
78+
</ui5-avatar>
79+
<div class="variant-description">
80+
<div class="variant-title">Interactive Avatar with Badge</div>
81+
<div class="variant-note">Badge recommended on interactive avatars</div>
82+
</div>
83+
</div>
84+
85+
<!-- Interactive Avatar with Popup -->
86+
<div class="variant-group">
87+
<ui5-avatar
88+
id="popup-avt"
89+
size="M"
90+
mode="Interactive"
91+
initials="GH"
92+
color-scheme="Accent7"
93+
aria-label="User profile - click to open menu"
94+
aria-haspopup="menu">
95+
</ui5-avatar>
96+
<div class="variant-description">
97+
<div class="variant-title">Interactive Avatar with Popup Menu</div>
98+
<div class="variant-note">Indicates menu availability via aria-haspopup</div>
99+
</div>
100+
</div>
101+
102+
<!-- Decorative Avatar -->
103+
<div class="variant-group">
104+
<ui5-avatar size="M" initials="IJ" role="presentation"></ui5-avatar>
105+
<div class="variant-description">
106+
<div class="variant-title">Decorative Avatar</div>
107+
<div class="variant-note">Purely visual - hidden from screen readers</div>
108+
</div>
109+
</div>
110+
</div>
111+
112+
<!-- playground-fold -->
113+
<script type="module" src="main.js"></script>
114+
</body>
115+
116+
</html>
117+
<!-- playground-fold-end -->

‎packages/website/docs/_samples/main/Avatar/WithBadge/sample.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,20 @@
1111
<body style="background-color: var(--sapBackgroundColor); display: flex; align-items: center; column-gap: 0.5rem;">
1212
<!-- playground-fold-end -->
1313

14-
<ui5-avatar size="M" initials="JD" color-scheme="Accent5">
14+
<ui5-avatar mode="Interactive" size="M" initials="JD" color-scheme="Accent5">
1515
<ui5-avatar-badge icon="edit" state="None" slot="badge"></ui5-avatar-badge>
1616
</ui5-avatar>
1717

18-
<ui5-avatar size="M" icon="employee" color-scheme="Accent10">
18+
<ui5-avatar mode="Interactive" size="M" icon="employee" color-scheme="Accent10">
1919
<ui5-avatar-badge icon="alert" state="Critical" slot="badge"></ui5-avatar-badge>
2020
</ui5-avatar>
2121

22-
<ui5-avatar size="M">
22+
<ui5-avatar mode="Interactive" size="M">
2323
<img src="../assets/images/avatars/man_avatar_1.png" alt="Man Avatar 1" />
2424
<ui5-avatar-badge icon="sys-enter-2" state="Positive" slot="badge"></ui5-avatar-badge>
2525
</ui5-avatar>
2626

27-
<ui5-avatar size="M" shape="Square">
27+
<ui5-avatar mode="Interactive" size="M" shape="Square">
2828
<img src="../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5" />
2929
<ui5-avatar-badge icon="error" state="Negative" slot="badge"></ui5-avatar-badge>
3030
</ui5-avatar>

‎packages/website/docs/_samples/main/AvatarBadge/Basic/sample.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
<body style="background-color: var(--sapBackgroundColor); display: flex; align-items: center; column-gap: 0.5rem;">
1212
<!-- playground-fold-end -->
1313

14-
<ui5-avatar size="M">
14+
<ui5-avatar mode="Interactive" size="M">
1515
<ui5-avatar-badge icon="edit" slot="badge"></ui5-avatar-badge>
1616
</ui5-avatar>
1717

‎packages/website/docs/_samples/main/AvatarBadge/ValueStates/sample.html‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,23 @@
1111
<body style="background-color: var(--sapBackgroundColor); display: flex; align-items: center; column-gap: 0.5rem;">
1212
<!-- playground-fold-end -->
1313

14-
<ui5-avatar size="M" initials="PM" color-scheme="Accent6">
14+
<ui5-avatar mode="Interactive" size="M" initials="PM" color-scheme="Accent6">
1515
<ui5-avatar-badge icon="edit" state="None" slot="badge"></ui5-avatar-badge>
1616
</ui5-avatar>
1717

18-
<ui5-avatar size="M" initials="JD" color-scheme="Accent1">
18+
<ui5-avatar mode="Interactive" size="M" initials="JD" color-scheme="Accent1">
1919
<ui5-avatar-badge icon="sys-enter-2" state="Positive" slot="badge"></ui5-avatar-badge>
2020
</ui5-avatar>
2121

22-
<ui5-avatar size="M" initials="YM" color-scheme="Accent8">
22+
<ui5-avatar mode="Interactive" size="M" initials="YM" color-scheme="Accent8">
2323
<ui5-avatar-badge icon="alert" state="Critical" slot="badge"></ui5-avatar-badge>
2424
</ui5-avatar>
2525

26-
<ui5-avatar size="M" initials="KG" color-scheme="Accent10">
26+
<ui5-avatar mode="Interactive" size="M" initials="KG" color-scheme="Accent10">
2727
<ui5-avatar-badge icon="error" state="Negative" slot="badge"></ui5-avatar-badge>
2828
</ui5-avatar>
2929

30-
<ui5-avatar size="M" initials="PI" color-scheme="Accent5">
30+
<ui5-avatar mode="Interactive" size="M" initials="PI" color-scheme="Accent5">
3131
<ui5-avatar-badge icon="information" state="Information" slot="badge"></ui5-avatar-badge>
3232
</ui5-avatar>
3333

0 commit comments

Comments
 (0)