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.mjsindex 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.tsindex 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 anddiff --git a/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjs b/packages/cli/templates/blocks/components/Avatar/AvatarGroup.doc.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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."},+ ],},};