Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): use AvatarGroup in grouped avatar example (#2809)

Cindy Zhangf13d7ba4997e
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 44a4542cef..efc57893a1 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -404,8 +404,9 @@ async function generateComponentRegistry() {
if (doc.subComponentOf) {
// Extracted sub-component: lives in its parent's directory in its own
// .doc.mjs file. Inherits family fields (group, category, keywords,
- // theming, playground, importPath) from the directory's primary doc;
- // owns its name, description, props, and usage. Produces a registry
+ // theming, playground, importPath) from the directory's primary doc
+ // unless the sub-component doc overrides them; owns its name,
+ // description, props, and usage. Produces a registry
// entry identical to the legacy inline `components[]` expansion.
const parentMeta = dirPrimaryMeta || {};
const subName = (doc.name || '').replace(/^XDS/, '');
@@ -462,7 +463,11 @@ async function generateComponentRegistry() {
? doc.relatedComponents || [doc.subComponentOf]
: null,
relatedHooks: isHookEntry ? doc.relatedHooks || null : null,
- playground: isHookEntry ? null : parentMeta.playground ?? null,
+ playground: isHookEntry
+ ? null
+ : doc.playground
+ ? sanitizeForJson(doc.playground)
+ : parentMeta.playground ?? null,
});
}
} else if (doc.components && doc.components.length > 0) {
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 926f7924dd..0c7fb17ae7 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -163,6 +163,18 @@ describe('componentRegistry', () => {
expect(dialogHeader!.description.toLowerCase()).toContain('header');
});
+ it('sub-components can override inherited playground defaults', () => {
+ const core = components['@xds/core'];
+ const avatarGroupOverflow = core.find(
+ c => c.name === 'AvatarGroupOverflow',
+ );
+ expect(avatarGroupOverflow).toBeDefined();
+ expect(avatarGroupOverflow!.playground?.defaults).toMatchObject({
+ count: 2,
+ children: '+2',
+ });
+ });
+
it('Chat has many sub-components (standalone docs take priority over compound entries)', () => {
const core = components['@xds/core'];
// Chat compound doc has 14 sub-components, but ChatToolCalls and
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs
index 4d3c061489..3cf313b95a 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs
@@ -3,11 +3,11 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- exampleFor: 'Avatar',
+ exampleFor: 'AvatarGroup',
name: 'Avatar — Group',
displayName: 'Avatar — Group',
description: 'Overlap multiple avatars in a row to represent a group of people. Use for team lists, PR reviewers, or participant counts where you want to show faces without taking up much space.',
isReady: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Avatar', 'Layout', 'Text'],
+ componentsUsed: ['AvatarGroup', 'Avatar', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx
index 4c6d577828..37191f045b 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.tsx
@@ -3,9 +3,9 @@
'use client';
import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSAvatarGroup, XDSAvatarGroupOverflow} from '@xds/core/AvatarGroup';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
-import * as stylex from '@stylexjs/stylex';
const USERS = [
{
@@ -30,14 +30,6 @@ const USERS = [
},
];
-const groupStyles = stylex.create({
- overlap: (offset: number) => ({
- marginLeft: offset,
- borderRadius: '50%',
- border: '2px solid var(--color-background-surface, #fff)',
- }),
-});
-
export default function AvatarGroup() {
return (
<XDSStack direction="vertical" gap={8}>
@@ -45,41 +37,23 @@ export default function AvatarGroup() {
<XDSText type="supporting" color="secondary">
Team members
</XDSText>
- <XDSStack direction="horizontal" vAlign="center">
- {USERS.map((user, i) => (
- <XDSStack
- direction="vertical"
- key={user.name}
- {...stylex.props(groupStyles.overlap(i === 0 ? 0 : -10))}>
- <XDSAvatar src={user.src} name={user.name} size="medium" />
- </XDSStack>
+ <XDSAvatarGroup size="medium">
+ {USERS.map(user => (
+ <XDSAvatar key={user.name} src={user.src} name={user.name} />
))}
- <XDSStack
- direction="vertical"
- {...stylex.props(groupStyles.overlap(-10))}>
- <XDSAvatar name="+3" size="medium" />
- </XDSStack>
- </XDSStack>
+ <XDSAvatarGroupOverflow count={3} />
+ </XDSAvatarGroup>
</XDSStack>
<XDSStack direction="vertical" gap={3}>
<XDSText type="supporting" color="secondary">
Larger group
</XDSText>
- <XDSStack direction="horizontal" vAlign="center">
- {USERS.slice(0, 3).map((user, i) => (
- <XDSStack
- direction="vertical"
- key={user.name}
- {...stylex.props(groupStyles.overlap(i === 0 ? 0 : -14))}>
- <XDSAvatar src={user.src} name={user.name} size="medium" />
- </XDSStack>
+ <XDSAvatarGroup size="medium">
+ {USERS.slice(0, 3).map(user => (
+ <XDSAvatar key={user.name} src={user.src} name={user.name} />
))}
- <XDSStack
- direction="vertical"
- {...stylex.props(groupStyles.overlap(-14))}>
- <XDSAvatar name="+8" size="medium" />
- </XDSStack>
- </XDSStack>
+ <XDSAvatarGroupOverflow count={8} />
+ </XDSAvatarGroup>
</XDSStack>
</XDSStack>
);
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.doc.mjs b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.doc.mjs
new file mode 100644
index 0000000000..4256747da4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'AvatarGroupOverflow',
+ name: 'AvatarGroupOverflow — Custom Text',
+ displayName: 'Avatar Group Overflow — Custom Text',
+ description:
+ 'Provide short custom children such as 12+ when the overflow count needs compact product-specific formatting.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['AvatarGroupOverflow', 'AvatarGroup', 'Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.tsx b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.tsx
new file mode 100644
index 0000000000..772198de03
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowCustomText.tsx
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSAvatarGroup, XDSAvatarGroupOverflow} from '@xds/core/AvatarGroup';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const TEAM = [
+ {
+ name: 'Alex Daniels',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-05.jpg',
+ },
+ {
+ name: 'Ann Smith',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-30.jpg',
+ },
+ {
+ name: 'Carol Davis',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-60.jpg',
+ },
+];
+
+export default function AvatarGroupOverflowCustomText() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Team members
+ </XDSText>
+ <XDSAvatarGroup size="medium">
+ {TEAM.map(member => (
+ <XDSAvatar key={member.name} src={member.src} name={member.name} />
+ ))}
+ <XDSAvatarGroupOverflow count={12}>12+</XDSAvatarGroupOverflow>
+ </XDSAvatarGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.doc.mjs b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.doc.mjs
new file mode 100644
index 0000000000..eee64d1c9e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'AvatarGroupOverflow',
+ name: 'AvatarGroupOverflow — Default Count',
+ displayName: 'Avatar Group Overflow — Default Count',
+ description:
+ 'Use XDSAvatarGroupOverflow without children to render the standard +N overflow count.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['AvatarGroupOverflow', 'AvatarGroup', 'Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.tsx b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.tsx
new file mode 100644
index 0000000000..390d1a14f3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowDefault.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSAvatarGroup, XDSAvatarGroupOverflow} from '@xds/core/AvatarGroup';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const REVIEWERS = [
+ {
+ name: 'Alex Daniels',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-05.jpg',
+ },
+ {
+ name: 'Ann Smith',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-30.jpg',
+ },
+ {
+ name: 'Carol Davis',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-60.jpg',
+ },
+];
+
+export default function AvatarGroupOverflowDefault() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Reviewers
+ </XDSText>
+ <XDSAvatarGroup size="medium">
+ {REVIEWERS.map(reviewer => (
+ <XDSAvatar
+ key={reviewer.name}
+ src={reviewer.src}
+ name={reviewer.name}
+ />
+ ))}
+ <XDSAvatarGroupOverflow count={2} />
+ </XDSAvatarGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.doc.mjs b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.doc.mjs
new file mode 100644
index 0000000000..56e10e9aa1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'AvatarGroupOverflow',
+ name: 'AvatarGroupOverflow',
+ displayName: 'Avatar Group Overflow',
+ description:
+ 'Overflow indicators for hidden avatars, including the default +N label and custom count text.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['AvatarGroupOverflow', 'AvatarGroup', 'Avatar', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.tsx b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.tsx
new file mode 100644
index 0000000000..180ae196c0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AvatarGroupOverflow/AvatarGroupOverflowShowcase.tsx
@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSAvatarGroup, XDSAvatarGroupOverflow} from '@xds/core/AvatarGroup';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const USERS = [
+ {
+ name: 'Alex Daniels',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-05.jpg',
+ },
+ {
+ name: 'Ann Smith',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-30.jpg',
+ },
+ {
+ name: 'Carol Davis',
+ src: 'https://lookaside.facebook.com/assets/vs_datakit_profile_photos_t66173184/VS-Design-Tools-Datakit-60.jpg',
+ },
+];
+
+export default function AvatarGroupOverflowShowcase() {
+ return (
+ <XDSStack direction="vertical" gap={8}>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Default overflow
+ </XDSText>
+ <XDSAvatarGroup size="medium">
+ {USERS.map(user => (
+ <XDSAvatar key={user.name} src={user.src} name={user.name} />
+ ))}
+ <XDSAvatarGroupOverflow count={5} />
+ </XDSAvatarGroup>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Custom count text
+ </XDSText>
+ <XDSAvatarGroup size="medium">
+ {USERS.slice(0, 2).map(user => (
+ <XDSAvatar key={user.name} src={user.src} name={user.name} />
+ ))}
+ <XDSAvatarGroupOverflow count={12}>12+</XDSAvatarGroupOverflow>
+ </XDSAvatarGroup>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
index f66facae43..c2ac569e7d 100644
--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
@@ -7,13 +7,81 @@ export const docs = {
subComponentOf: 'AvatarGroup',
displayName: 'Avatar Group Overflow',
isHiddenFromOverview: true,
- description: 'Slot for custom overflow content inside XDSAvatarGroup. Replaces the default "+N" indicator when present.',
+ description:
+ 'Overflow indicator for XDSAvatarGroup. Shows a compact count for hidden avatars and can render custom count text or act as a button.',
props: [
+ {
+ name: 'count',
+ type: 'number',
+ description:
+ 'The number of hidden avatars. Used for the default `+N` label and the accessible label.',
+ required: true,
+ },
{
name: 'children',
type: 'ReactNode',
- description: 'Custom overflow content (button, popover trigger, etc.).',
- required: true,
+ description:
+ 'Optional custom count text rendered inside the indicator. Omit to use the default `+N` label.',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description:
+ 'Callback fired when the overflow indicator is clicked. When provided, the indicator renders as a focusable button.',
+ },
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLElement>',
+ description: 'Ref forwarded to the overflow indicator element.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization.',
+ },
+ ],
+ playground: {
+ defaults: {
+ count: 2,
+ children: '+2',
+ },
+ },
+ usage: {
+ description:
+ 'AvatarGroupOverflow appears at the end of an XDSAvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.',
+ bestPractices: [
+ {guidance: true, description: 'Pass the real hidden count to `count` so the accessible label matches the visible indicator.'},
+ {guidance: true, description: 'Use short custom text such as `+12` or `99+`; the indicator is sized like an avatar.'},
+ {guidance: true, description: 'Provide `onClick` when the overflow opens a member list, popover, or detail view.'},
+ {guidance: false, description: 'Do not use long labels inside the indicator; place longer participant details next to the group instead.'},
+ ],
+ anatomy: [
+ {name: 'Count label', required: true, description: 'The compact `+N` or custom count text displayed inside the circular indicator.'},
+ {name: 'Button behavior', required: false, description: 'When `onClick` is provided, the indicator becomes an interactive button with focus and hover states.'},
+ ],
+ },
+ examples: [
+ {
+ label: 'Default overflow count',
+ code: `
+<XDSAvatarGroup size="medium">
+ {users.slice(0, 3).map(user => (
+ <XDSAvatar key={user.id} src={user.src} name={user.name} />
+ ))}
+ <XDSAvatarGroupOverflow count={users.length - 3} />
+</XDSAvatarGroup>
+`,
+ },
+ {
+ label: 'Custom count text',
+ code: `
+<XDSAvatarGroup size="medium">
+ {users.slice(0, 3).map(user => (
+ <XDSAvatar key={user.id} src={user.src} name={user.name} />
+ ))}
+ <XDSAvatarGroupOverflow count={12}>12+</XDSAvatarGroupOverflow>
+</XDSAvatarGroup>
+`,
},
],
};
@@ -22,9 +90,24 @@ export const docsZh = {
name: 'AvatarGroupOverflow',
isHiddenFromOverview: true,
displayName: 'Avatar Group Overflow',
- description: 'XDSAvatarGroup 内的自定义溢出内容插槽。存在时替换默认的 "+N" 指示器。',
+ description:
+ 'XDSAvatarGroup 的溢出指示器。用于显示隐藏头像数量,可自定义计数字符串或作为按钮使用。',
propDescriptions: {
- children: '自定义溢出内容(按钮、弹出触发器等)。',
+ count: '隐藏头像数量,用于默认 `+N` 标签和无障碍标签。',
+ children: '可选的自定义计数字符串。省略时使用默认 `+N` 标签。',
+ onClick: '点击溢出指示器时触发。提供后指示器会渲染为可聚焦按钮。',
+ ref: '转发到溢出指示器元素的引用。',
+ xstyle: '用于布局自定义的 StyleX 样式。',
+ },
+ usage: {
+ description:
+ 'AvatarGroupOverflow 显示在 XDSAvatarGroup 末尾,用来汇总未单独展示的成员。适用于只展示少量头像但仍需要显示隐藏数量的场景。',
+ bestPractices: [
+ {guidance: true, description: '向 `count` 传入真实隐藏数量,确保无障碍标签与可见指示器一致。'},
+ {guidance: true, description: '使用 `+12` 或 `99+` 等短文本;指示器尺寸与头像相同。'},
+ {guidance: true, description: '当溢出项会打开成员列表、弹出层或详情视图时提供 `onClick`。'},
+ {guidance: false, description: '不要在指示器内使用长标签;更长的参与者详情应放在头像组旁边。'},
+ ],
},
};
@@ -32,8 +115,22 @@ export const docsDense = {
name: 'AvatarGroupOverflow',
isHiddenFromOverview: true,
displayName: 'Avatar Group Overflow',
- description: 'custom overflow slot, replaces default +N',
+ description: 'overflow indicator for XDSAvatarGroup; default +N or custom short count text',
propDescriptions: {
- children: 'custom overflow content',
+ count: 'hidden avatar count; drives default +N + aria label',
+ children: 'optional custom short count text, e.g. +12 or 99+',
+ onClick: 'click handler; renders focusable button when set',
+ ref: 'forwarded ref',
+ xstyle: 'StyleX layout customization',
+ },
+ usage: {
+ description:
+ 'Use at end of XDSAvatarGroup to summarize hidden people after slicing visible avatars.',
+ bestPractices: [
+ {guidance: true, description: 'Pass real hidden count to `count` for a11y.'},
+ {guidance: true, description: 'Keep custom text short: `+12`, `99+`.'},
+ {guidance: true, description: 'Use `onClick` to open member list/popover/details.'},
+ {guidance: false, description: "Don't use long labels inside avatar-sized circle."},
+ ],
},
};