An open source design system that's fully customizable and agent ready
TypeScript
fix(AvatarGroup): keep the overlap when avatars are wrapped (#6736)
ksyingf839b67cc64f
diff --git a/.changeset/avatar-group-wrapped-overlap.md b/.changeset/avatar-group-wrapped-overlap.mdnew file mode 100644index 0000000000..7806184280--- /dev/null+++ b/.changeset/avatar-group-wrapped-overlap.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] AvatarGroup keeps its overlap when avatars are wrapped in a HoverCard or Tooltip. Every avatar and the overflow indicator now take the overlap margin, and the group pads its start edge to match, so the overlap no longer depends on each avatar being a direct child of the group.++@ksyingdiff --git a/apps/storybook/stories/AvatarGroup.stories.tsx b/apps/storybook/stories/AvatarGroup.stories.tsxindex ad02150ead..0b988b8eeb 100644--- a/apps/storybook/stories/AvatarGroup.stories.tsx+++ b/apps/storybook/stories/AvatarGroup.stories.tsx@@ -3,6 +3,7 @@ import type {Meta, StoryObj} from '@storybook/react';import * as stylex from '@stylexjs/stylex';import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';import {Avatar} from '@astryxdesign/core/Avatar';+import {HoverCard} from '@astryxdesign/core/HoverCard';import {StatusDot} from '@astryxdesign/core/StatusDot';import {spacingVars,@@ -313,6 +314,23 @@ export const StaticFacepile: Story = {),};+/**+ * Each avatar wrapped in a HoverCard. The avatars still overlap, and hovering+ * one shows that person's card.+ */+export const WithHoverCards: Story = {+ render: () => (+ <AvatarGroup size="lg" data-testid="avatar-group-hover-cards">+ {USERS.slice(0, 4).map(u => (+ <HoverCard key={u.key} content={u.name}>+ <Avatar src={u.src} name={u.name} tooltip={false} />+ </HoverCard>+ ))}+ <AvatarGroupOverflow count={USERS.length - 4} />+ </AvatarGroup>+ ),+};+/*** Right-to-left. The overlap is an inline-margin effect, so it mirrors: the* stack builds from the right and each avatar overlaps the one before it bydiff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsindex 59aff2ac17..04e2bf0430 100644--- a/packages/core/src/Avatar/Avatar.doc.mjs+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -36,7 +36,7 @@ export const docs = {{className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},],vars: [- {name: '--_avatar-group-overlap', description: 'Negative inline offset applied to every avatar after the first when avatars are stacked in an AvatarGroup. Set from the group size; a more negative value tightens the stack.', default: 'set at runtime from the group avatar size (px)', private: true},+ {name: '--_avatar-group-overlap', description: 'Negative inline offset applied to every avatar stacked in an AvatarGroup; the group pads its start edge by the same amount so the first avatar stays inside it. Set from the group size; a more negative value tightens the stack.', default: 'set at runtime from the group avatar size (px)', private: true},{name: '--_avatar-radius', description: 'Border radius of the avatar wrapper, content, focus ring, and the AvatarGroupOverflow "+N" chip. Set per shape variant by shapeStyles.', default: 'var(--radius-full)', private: true},],derived: [diff --git a/packages/core/src/Avatar/Avatar.tsx b/packages/core/src/Avatar/Avatar.tsxindex 084c5c4ecb..01de6d4729 100644--- a/packages/core/src/Avatar/Avatar.tsx+++ b/packages/core/src/Avatar/Avatar.tsx@@ -267,11 +267,12 @@ const groupStyles = stylex.create({backgroundColor: colorVars['--color-background-surface'],boxSizing: 'content-box',},+ // Every avatar takes the overlap, not just `:not(:first-child)`: a+ // HoverCard or Tooltip wraps its trigger in its own element, which makes+ // every wrapped avatar a first child. AvatarGroup pads its start edge by the+ // same amount so the first avatar still sits inside the group's box.overlap: {- marginInlineStart: {- default: null,- ':not(:first-child)': 'var(--_avatar-group-overlap)',- },+ marginInlineStart: 'var(--_avatar-group-overlap)',},});diff --git a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjsindex 6b1ea01c1f..5605d90254 100644--- a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs+++ b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs@@ -14,6 +14,7 @@ export const docs = {{guidance: true, description: 'Slice the list yourself and pass only the avatars you want visible; 3-5 is typical. The group renders exactly the children it is given and never slices for you.'},{guidance: true, description: 'Use AvatarGroupOverflow for custom overflow content like a popover trigger or "add member" button.'},{guidance: true, description: 'Pass status dots, click handlers, or tooltips directly on each Avatar child.'},+ {guidance: true, description: 'Wrap an Avatar child in HoverCard or Tooltip to show more on hover; the avatars still overlap. Set tooltip={false} on the wrapped Avatar so its built-in name tooltip does not compete.'},{guidance: true, description: 'Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech. This follows the WAI-ARIA APG roving tabindex technique for managing focus in a composite: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},{guidance: false, description: "Don't nest AvatarGroups; use a single group with all avatars."},{guidance: false, description: "Don't set size on the child avatars. The group's size wins over each child's own size prop, including when the group leaves size at its default, so a child's size is silently ignored inside a group."},@@ -88,6 +89,7 @@ export const docsZh = {{guidance: true, description: '自行切分列表,只传入需要显示的头像,通常 3-5 个为佳。组件只渲染传入的子元素,不会自动切分。'},{guidance: true, description: '使用 AvatarGroupOverflow 自定义溢出内容,如弹出触发器或"添加成员"按钮。'},{guidance: true, description: '直接在每个 Avatar 子元素上传递状态点、点击处理器或工具提示。'},+ {guidance: true, description: '可以用 HoverCard 或 Tooltip 包裹 Avatar 子元素以在悬停时显示更多信息,头像仍会重叠。请在被包裹的 Avatar 上设置 tooltip={false},避免与内置的名称提示冲突。'},{guidance: false, description: '不要嵌套 AvatarGroup,使用单个组包含所有头像。'},{guidance: false, description: '不要在子头像上设置 size。分组的 size 会覆盖每个子 Avatar 自身的 size,即使分组使用默认值也是如此。'},],@@ -104,6 +106,7 @@ export const docsDense = {{guidance: true, description: 'Slice the list yourself; pass only visible avatars (3-5 typical). No auto-slicing.'},{guidance: true, description: 'Use AvatarGroupOverflow for custom overflow (popover, add button).'},{guidance: true, description: 'Pass status dots / click handlers directly on each Avatar.'},+ {guidance: true, description: 'Avatars may be wrapped in HoverCard/Tooltip; overlap kept. Set tooltip={false} on the wrapped Avatar.'},{guidance: true, description: 'Interactive avatars (href/onClick) share one Tab stop; arrows rove between them + the overflow button (APG roving tabindex).'},{guidance: false, description: "Don't nest AvatarGroups."},{guidance: false, description: "Don't set size on children; the group's size always wins, default included."},diff --git a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx b/packages/core/src/AvatarGroup/AvatarGroup.test.tsxindex 93d5ce6f2c..e90f932836 100644--- a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx@@ -5,6 +5,8 @@ import userEvent from '@testing-library/user-event';import {AvatarGroup} from './AvatarGroup';import {AvatarGroupOverflow} from './AvatarGroupOverflow';import {Avatar, AvatarStatusDot} from '../Avatar';+import {HoverCard} from '../HoverCard';+import {Tooltip} from '../Tooltip';describe('AvatarGroup', () => {it('renders all avatar children', () => {@@ -214,6 +216,71 @@ describe('AvatarGroup — roving focus + keyboard hint', () => {});});+describe('AvatarGroup — overlap', () => {+ // jsdom cannot lay the row out, so these check the declarations that make+ // it overlap: every item takes the negative overlap margin, and the group's+ // start padding gives the first item that space back.+ const overlapMargin = (el: HTMLElement) =>+ getComputedStyle(el).getPropertyValue('margin-inline-start');++ it('overlaps every avatar, including the first', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" data-testid="alice" />+ <Avatar name="Bob" data-testid="bob" />+ <AvatarGroupOverflow count={2} data-testid="overflow" />+ </AvatarGroup>,+ );++ for (const id of ['alice', 'bob', 'overflow']) {+ expect(overlapMargin(screen.getByTestId(id))).toBe(+ 'var(--_avatar-group-overlap)',+ );+ }+ const group = screen.getByRole('group');+ expect(+ getComputedStyle(group).getPropertyValue('padding-inline-start'),+ ).toBe('calc(-1 * var(--_avatar-group-overlap))');+ // md = 36px; the overlap is a quarter of that, negated.+ expect(group.getAttribute('style')).toContain('-9px');+ });++ it('keeps the overlap when avatars are wrapped in a HoverCard or Tooltip', () => {+ // Both wrap their trigger in a `display: contents` element, so each avatar+ // is the first child of its own wrapper. A `:not(:first-child)` rule+ // would never match.+ render(+ <AvatarGroup>+ <HoverCard content="Alice's card">+ <Avatar name="Alice" data-testid="alice" />+ </HoverCard>+ <HoverCard content="Bob's card">+ <Avatar name="Bob" data-testid="bob" />+ </HoverCard>+ <Tooltip content="Charlie">+ <Avatar name="Charlie" data-testid="charlie" />+ </Tooltip>+ </AvatarGroup>,+ );++ for (const id of ['alice', 'bob', 'charlie']) {+ const avatar = screen.getByTestId(id);+ expect(avatar.parentElement).not.toBe(screen.getByRole('group'));+ expect(overlapMargin(avatar)).toBe('var(--_avatar-group-overlap)');+ }+ });++ it('adds no start padding to an empty group', () => {+ render(<AvatarGroup data-testid="empty">{[]}</AvatarGroup>);++ expect(+ getComputedStyle(screen.getByTestId('empty')).getPropertyValue(+ 'padding-inline-start',+ ),+ ).toMatch(/^0(px)?$/);+ });+});+describe('AvatarGroup — size cascade', () => {it("the group's size overrides a child's own size prop", () => {render(diff --git a/packages/core/src/AvatarGroup/AvatarGroup.tsx b/packages/core/src/AvatarGroup/AvatarGroup.tsxindex aaf28752f1..45f2b85214 100644--- a/packages/core/src/AvatarGroup/AvatarGroup.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroup.tsx@@ -9,7 +9,8 @@** Compositional API: children are Avatar elements (and optionally* one AvatarGroupOverflow). The group provides overlap styling via- * context — no child introspection needed.+ * context — no child introspection needed. The overlap does not depend on+ * child position, so avatars can be wrapped in HoverCard or Tooltip.** When the group contains interactive avatars (rendered as links/buttons) or an* interactive AvatarGroupOverflow, it becomes a single Tab stop with roving@@ -72,9 +73,23 @@ const styles = stylex.create({root: {display: 'inline-flex',alignItems: 'center',+ // Every avatar (and the overflow indicator) takes the negative overlap+ // margin, including the first one, so the overlap survives wrappers such+ // as HoverCard and Tooltip. This padding gives the first child that space+ // back, keeping the row inside the group's box.+ paddingInlineStart: {+ default: 'calc(-1 * var(--_avatar-group-overlap))',+ ':empty': 0,+ },},});+const dynamicStyles = stylex.create({+ overlap: (offset: number) => ({+ '--_avatar-group-overlap': `${offset}px`,+ }),+});+/*** Stacked avatar display showing multiple avatars overlapping with an* optional overflow indicator. Uses a compositional children-based API@@ -161,7 +176,7 @@ export function AvatarGroup({onFocus={composeEventHandlers(onFocus, handleFocus)}{...mergeProps(themeProps('avatar-group', {size, shape}),- stylex.props(styles.root, xstyle),+ stylex.props(styles.root, dynamicStyles.overlap(-overlap), xstyle),className,style,)}>diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.md b/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.mdindex 3617734b86..5c46817206 100644--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.md+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.md@@ -95,7 +95,7 @@ current observable concepts rather than duplicating its prop table.| FR1 | Without the existing activation callback, the current render uses one span; with the callback, it uses one native `button` with `type="button"` and invokes that callback on native activation. | Current source, consumer docs, tests, and rendered evidence | Verified shipped behavior; no new activation meaning decided || FR2 | The current rendered amount never displays a negative value: negative input normalizes to zero before both the translated accessible label and default `+N` content are produced. Caller-supplied child content replaces only the visible default content. | Current source, docs, and tests | Verified shipped behavior; no new validation policy decided || FR3 | Inside AvatarGroup, the indicator currently consumes the group's resolved size, shape, and overlap. Outside a group, it currently uses the medium size, circle shape, and zero overlap. | Current source, tests, stories, and browser evidence | Verified shipped behavior; no context contract change |-| FR4 | The current root remains at least as wide as the resolved avatar size, grows inline for wider content, keeps the resolved avatar height, and applies overlap only when it is not the first child. | Current source and browser evidence | Verified shipped layout; no new geometry requirement introduced |+| FR4 | The current root remains at least as wide as the resolved avatar size, grows inline for wider content, keeps the resolved avatar height, and applies the overlap margin in every position; AvatarGroup pads its start edge to match, so a first-child indicator stays inside the group. | Current source and browser evidence | Verified shipped layout; no new geometry requirement introduced || FR5 | The current root carries the `avatar-group-overflow` target with size and shape reflection, then combines component styles with supported consumer StyleX, class, and style inputs on that same element. | Current source, docs, target tests, and browser evidence | Verified shipped theming and passthrough behavior || FR6 | An indicator with the current activation callback carries AvatarGroup's item marker and participates in AvatarGroup's existing roving-focus sequence. The static span branch carries no group item marker and is non-interactive by default; supported caller-provided DOM props such as `tabIndex` still reach that span and may make it programmatically or sequentially focusable according to the supplied value. | Current source, BaseProps passthrough, and AvatarGroup interaction tests | Verified composition and passthrough; AvatarGroup retains roving-focus ownership |diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsxindex 9cbb602ad8..158c2d6e9f 100644--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx@@ -101,12 +101,10 @@ const styles = stylex.create({// Focus ring via focus-visible},overlap: {- // Matches Avatar's own overlap rule: the first item in the row must not be- // pulled outside the group's box.- marginInlineStart: {- default: null,- ':not(:first-child)': 'var(--_avatar-group-overlap)',- },+ // Matches Avatar's own overlap rule. AvatarGroup pads its start edge by+ // the same amount, so the indicator stays inside the group's box even+ // when it is the first child.+ marginInlineStart: 'var(--_avatar-group-overlap)',},});