An open source design system that's fully customizable and agent ready
TypeScript
test(AvatarGroupOverflow): add component-scoped audit coverage (#6120)
Cindy Zhang3d0bea6d29b6
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex 44b70b8aec..d5c4cb276a 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -424,5 +424,16 @@"overlay": ".astryx-rich-text-editor > div:first-child > div:last-child","overlayRoot": ".astryx-rich-text-editor"}+ },+ {+ "component": "AvatarGroupOverflow",+ "storyId": "core-avatargroupoverflow--default",+ "dims": [+ "D2"+ ],+ "selectors": {+ "prev": ".astryx-avatar-group > .astryx-avatar:first-child",+ "next": ".astryx-avatar-group-overflow"+ }}]diff --git a/apps/storybook/stories/AvatarGroupOverflow.stories.tsx b/apps/storybook/stories/AvatarGroupOverflow.stories.tsxnew file mode 100644index 0000000000..cbdeeb29e8--- /dev/null+++ b/apps/storybook/stories/AvatarGroupOverflow.stories.tsx@@ -0,0 +1,148 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+import type {Meta, StoryObj} from '@storybook/react';+import {fn} from 'storybook/test';+import * as stylex from '@stylexjs/stylex';+import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';+import {Avatar} from '@astryxdesign/core/Avatar';+import {+ spacingVars,+ typographyVars,+} from '@astryxdesign/core/theme/tokens.stylex';++const storyStyles = stylex.create({+ column: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-6'],+ },+ row: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-4'],+ flexWrap: 'wrap',+ },+ item: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-2'],+ },+ label: {+ fontFamily: typographyVars['--font-family-body'],+ margin: 0,+ },+ narrow: {+ width: 120,+ },+});++const meta: Meta<typeof AvatarGroupOverflow> = {+ title: 'Core/AvatarGroupOverflow',+ component: AvatarGroupOverflow,+ tags: ['autodocs'],+ args: {+ count: 2,+ onClick: undefined,+ },+ argTypes: {+ count: {control: 'number'},+ children: {control: 'text'},+ onClick: {+ control: false,+ description: 'Callback for intentionally clickable overflow indicators.',+ },+ ref: {control: false},+ xstyle: {+ control: false,+ description: 'stylex.create() value — not an inline style object.',+ },+ },+ render: args => (+ <AvatarGroup size="lg">+ <Avatar name="Alice" />+ <Avatar name="Bob" />+ <AvatarGroupOverflow {...args} />+ </AvatarGroup>+ ),+};++export default meta;+type Story = StoryObj<typeof AvatarGroupOverflow>;++export const Default: Story = {};++export const Clickable: Story = {+ args: {+ onClick: fn(),+ },+};++export const CustomContent: Story = {+ args: {+ count: 12,+ children: '12+',+ },+};++export const AllSizes: Story = {+ render: () => (+ <div {...stylex.props(storyStyles.column)}>+ {(['xsm', 'sm', 'md', 'lg', 'xl'] as const).map(size => (+ <div key={size} {...stylex.props(storyStyles.item)}>+ <p {...stylex.props(storyStyles.label)}>{size}</p>+ <AvatarGroup size={size}>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={2} />+ </AvatarGroup>+ </div>+ ))}+ </div>+ ),+};++export const AllShapes: Story = {+ render: () => (+ <div {...stylex.props(storyStyles.row)}>+ {(['circle', 'rounded', 'square'] as const).map(shape => (+ <div key={shape} {...stylex.props(storyStyles.item)}>+ <p {...stylex.props(storyStyles.label)}>{shape}</p>+ <AvatarGroup size="lg" shape={shape}>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={2} />+ </AvatarGroup>+ </div>+ ))}+ </div>+ ),+};++export const LargeCount: Story = {+ args: {+ count: 4912,+ },+};++export const ZeroCount: Story = {+ args: {+ count: 0,+ },+};++export const Standalone: Story = {+ render: args => <AvatarGroupOverflow {...args} />,+};++export const RightToLeft: Story = {+ globals: {direction: 'rtl'},+};++export const NarrowContainer: Story = {+ render: args => (+ <div {...stylex.props(storyStyles.narrow)}>+ <AvatarGroup size="lg">+ <Avatar name="Alice" />+ <Avatar name="Bob" />+ <AvatarGroupOverflow {...args} />+ </AvatarGroup>+ </div>+ ),+};diff --git a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx b/packages/core/src/AvatarGroup/AvatarGroup.test.tsxindex f24a5b3cc7..282eb580e5 100644--- a/packages/core/src/AvatarGroup/AvatarGroup.test.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroup.test.tsx@@ -1,11 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect, vi} from 'vitest';+import {describe, it, expect} from 'vitest';import {render, screen} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {AvatarGroup} from './AvatarGroup';import {AvatarGroupOverflow} from './AvatarGroupOverflow';import {Avatar, AvatarStatusDot} from '../Avatar';-import {InternationalizationProvider} from '../i18n';describe('AvatarGroup', () => {it('renders all avatar children', () => {@@ -90,241 +89,6 @@ describe('AvatarGroup', () => {});});-describe('AvatarGroupOverflow', () => {- it('renders overflow count as span by default', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={5} />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('5 more');- expect(overflow.tagName).toBe('SPAN');- expect(overflow).toHaveTextContent('+5');- });-- it('applies the group size class to the overflow chip', () => {- render(- <AvatarGroup size="lg">- <Avatar name="Alice" />- <AvatarGroupOverflow count={5} />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('5 more');- expect(overflow.className).toContain('astryx-avatar-group-overflow');- expect(overflow.className).toContain('lg');- expect(overflow).toHaveAttribute('data-size', 'lg');- });-- it('applies the group shape to the overflow chip, matching its avatars', () => {- render(- <AvatarGroup shape="square">- <Avatar name="Alice" />- <AvatarGroupOverflow count={5} />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('5 more');- expect(overflow).toHaveAttribute('data-shape', 'square');- });-- it('defaults the overflow chip to circle shape with no explicit AvatarGroup shape', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={5} />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('5 more');- expect(overflow).toHaveAttribute('data-shape', 'circle');- });-- it('renders as button when onClick is provided', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} onClick={() => {}} />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('3 more');- expect(overflow.tagName).toBe('BUTTON');- });-- it('calls onClick when clicked', async () => {- const user = userEvent.setup();- const handleClick = vi.fn();-- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} onClick={handleClick} />- </AvatarGroup>,- );-- await user.click(screen.getByLabelText('3 more'));- expect(handleClick).toHaveBeenCalledOnce();- });-- it('renders custom children instead of default label', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={5}>- <span data-testid="custom">more</span>- </AvatarGroupOverflow>- </AvatarGroup>,- );-- expect(screen.getByTestId('custom')).toBeInTheDocument();- });-- it('works with sliced avatar list and server-side count', () => {- const users = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];- const serverTotal = 47;- const visibleCount = 3;-- render(- <AvatarGroup size="lg">- {users.slice(0, visibleCount).map(name => (- <Avatar key={name} name={name} />- ))}- <AvatarGroupOverflow count={serverTotal - visibleCount} />- </AvatarGroup>,- );-- expect(screen.getByLabelText('Alice')).toBeInTheDocument();- expect(screen.getByLabelText('Bob')).toBeInTheDocument();- expect(screen.getByLabelText('Charlie')).toBeInTheDocument();- expect(screen.getByLabelText('44 more')).toBeInTheDocument();- expect(screen.getByText('+44')).toBeInTheDocument();- });-});--describe('AvatarGroupOverflow — hardening', () => {- it('forwards ref to the span element', () => {- const ref = {current: null} as React.RefObject<HTMLElement | null>;-- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} ref={ref} />- </AvatarGroup>,- );-- expect(ref.current).toBeInstanceOf(HTMLSpanElement);- });-- it('forwards ref to the button element when onClick provided', () => {- const ref = {current: null} as React.RefObject<HTMLElement | null>;-- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} onClick={() => {}} ref={ref} />- </AvatarGroup>,- );-- expect(ref.current).toBeInstanceOf(HTMLButtonElement);- });-- it('applies className prop', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} className="custom-class" />- </AvatarGroup>,- );-- const overflow = screen.getByLabelText('3 more');- expect(overflow.className).toContain('custom-class');- });-- it('handles count of zero gracefully', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={0} />- </AvatarGroup>,- );-- expect(screen.getByText('+0')).toBeInTheDocument();- expect(screen.getByLabelText('0 more')).toBeInTheDocument();- });-- it('clamps a negative count rather than rendering "+-3"', () => {- // `count={total - visibleCount}` is the documented shape, and it goes- // negative whenever the list is shorter than the slice.- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={-3} />- </AvatarGroup>,- );-- expect(screen.queryByText('+-3')).not.toBeInTheDocument();- expect(screen.getByText('+0')).toBeInTheDocument();- expect(screen.getByLabelText('0 more')).toBeInTheDocument();- });-- it('renders outside an AvatarGroup at the md fallback size', () => {- render(<AvatarGroupOverflow count={3} data-testid="loose" />);-- const overflow = screen.getByTestId('loose');- expect(overflow).toHaveTextContent('+3');- // inline-flex, so a standalone indicator stays a circle instead of- // stretching to its parent's width.- expect(overflow.tagName).toBe('SPAN');- });-- it('handles very large count', () => {- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={999} />- </AvatarGroup>,- );-- expect(screen.getByText('+999')).toBeInTheDocument();- });-- it('renders the full "+N" text for wide multi-digit counts', () => {- // The indicator grows into a pill for long counts, so the entire number- // must remain present (nothing clipped away in the DOM).- render(- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={4912} />- </AvatarGroup>,- );-- expect(screen.getByText('+4912')).toBeInTheDocument();- // The aria-label routes through the catalog's `{count, number}` ICU- // argument, so the en locale adds a grouping separator.- expect(screen.getByLabelText('4,912 more')).toBeInTheDocument();- });-- it('localizes the overflow label through the i18n catalog', () => {- render(- <InternationalizationProvider- locale="fr"- overrides={{- fr: {'@astryx.avatarGroup.overflow': '{count, number} de plus'},- }}>- <AvatarGroup>- <Avatar name="Alice" />- <AvatarGroupOverflow count={3} />- </AvatarGroup>- </InternationalizationProvider>,- );-- expect(screen.getByLabelText('3 de plus')).toBeInTheDocument();- });-});-describe('AvatarGroup — roving focus + keyboard hint', () => {it('is a single tab stop over interactive avatars (one tabindex=0, rest -1)', () => {render(diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjsindex 5973d267b2..f0daa3d9b2 100644--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs@@ -37,7 +37,7 @@ export const docs = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization.',+ description: 'stylex.create() value — not an inline style object.',},],playground: {@@ -53,6 +53,7 @@ export const docs = {{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 circular for short counts and grows into a pill for wider counts so the number always fits.'},{guidance: true, description: 'Provide `onClick` when the overflow opens a member list, popover, or detail view.'},+ {guidance: false, description: 'Do not pass custom text that disagrees with `count`; `count` continues to provide the accessible label.'},{guidance: false, description: 'Do not use long labels inside the indicator; place longer participant details next to the group instead.'},],anatomy: [@@ -106,6 +107,7 @@ export const docsZh = {{guidance: true, description: '向 `count` 传入真实隐藏数量,确保无障碍标签与可见指示器一致。'},{guidance: true, description: '使用 `+12` 或 `99+` 等短文本;指示器在计数较短时为圆形,计数较宽时会拉伸为胶囊形,确保数字始终完整显示。'},{guidance: true, description: '当溢出项会打开成员列表、弹出层或详情视图时提供 `onClick`。'},+ {guidance: false, description: '不要让自定义文本与 `count` 不一致;`count` 仍用于无障碍标签。'},{guidance: false, description: '不要在指示器内使用长标签;更长的参与者详情应放在头像组旁边。'},],},@@ -121,7 +123,7 @@ export const docsDense = {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',+ xstyle: 'stylex.create() value — not an inline style object',},usage: {description:@@ -130,6 +132,7 @@ export const docsDense = {{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 let custom text disagree with `count`; `count` still labels the indicator for accessibility."},{guidance: false, description: "Don't use long labels inside avatar-sized circle."},],},diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.md b/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.mdnew file mode 100644index 0000000000..3617734b86--- /dev/null+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.spec.md@@ -0,0 +1,207 @@+---+schema_version: 3+template_version: 4+kind: component+id: component:AvatarGroupOverflow+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, layout, theming, accessibility]+verified_by:+ [+ packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx,+ packages/core/src/AvatarGroup/AvatarGroup.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ packages/core/src/theme/derivedVarRegistry.test.ts,+ apps/storybook/rtl-audit/targets.json,+ scripts/check-knowledge.mjs,+ ]+modules: []+families: []+design_specs: []+architecture:+ [+ architecture:knowledge-contracts,+ architecture:component-theming-surface,+ architecture:public-component-api,+ ]+contributing: []+system_specs: [spec:AST-002, spec:AST-029]+---++# AvatarGroupOverflow component contract++## Intent++AvatarGroupOverflow presents the current compact overflow amount associated with+an AvatarGroup. It renders a default count or caller-supplied content and may use+a native button when the existing activation callback is present. This draft+records verified shipped behavior only. It does not change runtime behavior,+public API, compatibility, targets, or product meaning.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: additive observational documentation only; runtime, DOM,+ accessibility, styling, targets, defaults, and public API remain unchanged+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The overflow indicator element and its current `avatar-group-overflow` theming+ target.+- The current default visible count content and translated accessible count label.+- The current static-element and native-button render branches.+- The standalone presentation fallback used outside AvatarGroup.++**Does not own / non-goals**++- Choosing which avatars are visible or calculating the hidden count; the product+ callsite supplies the count and Avatar children.+- Avatar content, image loading, fallback initials, status, and Avatar theming;+ those remain owned by `component:Avatar` when that contract exists.+- AvatarGroup's group label, context lifetime, child ordering, or roving-focus+ algorithm. AvatarGroupOverflow only participates through the current rendered+ marker when it is interactive.+- Caller-supplied custom child content beyond rendering it in the current slot.+- New API meaning, validation, defaults, compatibility promises, or visual+ treatment.++## Public concepts++Consumer syntax remains in `AvatarGroupOverflow.doc.mjs`. This table records the+current observable concepts rather than duplicating its prop table.++| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |+| Overflow amount | Numeric amount supplied by the caller | Drives the current translated accessible label and the default visible `+N` content. | Static and interactive branches; inside or outside AvatarGroup. | Required caller input. | `component:AvatarGroupOverflow` | Observed released surface | Negative values currently normalize to zero; this draft does not specify other runtime-invalid values. |+| Display content | Default count content or caller-supplied React content | Selects the visible content inside the indicator without replacing the count-derived accessible label. | Both render branches. | Default `+N` content when custom content is absent. | `component:AvatarGroupOverflow` for the default; caller for supplied content | Observed released surface | React rendering determines caller-content behavior. |+| Activation mode | Static or clickable | Absence of the current callback renders a span; presence renders a native button and invokes the callback on activation. | Both standalone and grouped use. | Static. | `component:AvatarGroupOverflow` | Observed released surface | The typed callback boundary accepts a function or is absent. |+| Group presentation | Group-provided or standalone fallback | Group context currently supplies size, shape, and overlap; standalone use falls back to medium, circle, and no overlap. | All current size and shape values; LTR and RTL. | Standalone medium circle with zero overlap. | AvatarGroup context for grouped values; `component:AvatarGroupOverflow` for fallback application | Observed released surface | Type-rejected group values are outside this draft. |+| DOM extension | Supported BaseProps inputs and ref | Supported DOM, ARIA, data, event, class, style, and StyleX inputs reach the current root; ref reaches the rendered span or button. | Both render branches. | No additional inputs. | `architecture:public-component-api` | Observed released surface | BaseProps omissions remain unsupported. |++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |+| 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 |+| 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 |++### Allowed variation++- **AV1 — Amount and content.** The numeric amount and caller-supplied visible+ content may vary; wider content may grow the indicator inline.+- **AV2 — Group presentation.** Current AvatarGroup size and shape values may vary+ while the indicator continues to consume the group's resolved context.+- **AV3 — Styling inputs.** Supported consumer styling may vary through the current+ BaseProps and `avatar-group-overflow` target without moving the target to a+ different element.++### Representative states++| State | Required invariant | Allowed variation |+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |+| Static default count | One span presents the translated count label and visible `+N` content. It is non-interactive by default and remains outside AvatarGroup's roving-focus item set; supported caller DOM props such as `tabIndex` may make the span focusable according to the supplied value. | Count, group size, group shape, direction, supported consumer DOM/styling props, and resulting focusability may vary. |+| Static custom content | The span retains the count-derived accessible label while caller content replaces the visible default. Its default interaction and passthrough behavior match the static count branch. | Caller owns the custom React content; supported consumer DOM and styling props may vary. |+| Clickable count | One native button presents the count-derived accessible label, participates in the group marker when grouped, and invokes the existing callback. | Count, content, group presentation, and supported consumer inputs may vary. |+| Negative count | Accessible and default visible count content use zero rather than a negative value. | Caller-supplied visible content may still differ because it remains caller-owned. |+| Wide count | The indicator grows inline while retaining its resolved height and content. | Width follows rendered content and current padding. |+| Standalone | Medium circle and zero-overlap fallbacks apply without AvatarGroup context. | Count, custom content, activation mode, and consumer styles may vary. |+| RTL | Logical overlap and item order follow the document direction. | Count, content, size, shape, and activation may vary. |++### Transformation and precedence order++- **ORD1 — Resolve presentation.** AvatarGroup context currently supplies size,+ shape, numeric size, and overlap; missing context falls back to medium, circle,+ medium numeric size, and zero overlap.+- **ORD2 — Resolve content.** The numeric input is clamped at zero, then used for+ the translated accessible label; caller children replace only the default visible+ `+N` content.+- **ORD3 — Resolve root.** Callback presence selects the native-button or span+ branch. Component-owned semantics and target data remain on that root, and the+ current merge combines component styles with supported consumer styling inputs.++### Performance and resources++- No new performance or resource constraint is introduced. The observed component+ owns no state, Effect, listener, observer, timer, portal, or asynchronous resource.++## Accessibility contract++- **AR1 — Current accessible count.** Both current render branches expose the+ translator-produced count label derived from the normalized numeric amount.+- **AR2 — Current root semantics.** The activation-callback branch is a native+ `button` with `type="button"` and the shared focus-visible treatment. The static+ branch remains a span and is non-interactive by default; supported caller DOM+ props, including `tabIndex`, are forwarded and may alter its focusability.+- **AR3 — Current group participation.** The activation-callback branch carries+ the current AvatarGroup item marker so AvatarGroup's existing roving-focus owner+ may include it. The static branch carries no such marker even when caller DOM+ props make its span focusable. This draft does not copy or change AvatarGroup's+ focus algorithm.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | ------------------ |+| Count label | Presents compact supporting count content on the current indicator surface. | Current source and consumer docs | Supporting | FR2, FR4, AR1 |+| Button behavior | Uses the current native-button branch with shared overlay and focus-visible treatments. | Current source and shared utilities | Supporting action | FR1, FR6, AR2, AR3 |++This observational draft records the current representation and target placement.+It does not decide a new density, proportion, state treatment, or visual default.++## Family and system relationships++- `architecture:knowledge-contracts` owns draft/current authority, observational+ backfill boundaries, exact-head approval, and conflict routing.+- `architecture:component-theming-surface` owns painting-target qualification,+ target capability metadata, and size/shape state reflection on the current+ target.+- `architecture:public-component-api` owns the released subpath, BaseProps+ passthrough, styling composition, ref reachability, and compatibility boundary.+- `spec:AST-002` owns API admission and requires any future public or behavioral+ delta to identify current authority rather than deriving permission from this+ observational draft.+- `spec:AST-029` owns the Night Watch backfill procedure and keeps this draft from+ settling new behavior or changing product meaning.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |+| FR1, FR2, AR1, AR2 | `AvatarGroupOverflow.test.tsx` render, callback, content, count, ref, passthrough, and locale suites | Static default, static with caller DOM props, clickable, custom content, zero, negative, large, localized, and standalone | Changing the root branch, callback, normalized count, visible fallback, accessible label, supported DOM passthrough, or ref target fails focused public-interface assertions. | `audit:AvatarGroupOverflow/behavior` |+| FR3, FR4 | `AvatarGroupOverflow.test.tsx`, dedicated stories, and browser evidence | Every current size and shape, grouped, standalone, wide count, and narrow viewport | Losing context inheritance, fallbacks, shape reflection, standalone sizing, or wide-content containment fails focused assertions or rendered evidence. | `audit:AvatarGroupOverflow/layout` |+| FR5 | `themingTargets.test.ts`, `derivedVarRegistry.test.ts`, source inspection, and dedicated stories | Static and interactive roots across sizes and shapes | Target metadata, reflected axes, private overlap variable ownership, or painting-root placement drift fails guards or rendered inspection. | `audit:AvatarGroupOverflow/theming` |+| FR6, AR3 | `AvatarGroup.test.tsx` overflow-button roving-focus suite plus source/passthrough inspection | Activation-callback branch after an interactive Avatar; static span with and without caller `tabIndex` | Removing the marker from the callback branch breaks group participation; adding it to the static branch changes the observed roving set; dropping caller `tabIndex` contradicts BaseProps passthrough. | `audit:AvatarGroupOverflow/accessibility` |+| RTL relation | `apps/storybook/rtl-audit/targets.json` D2 target and `AvatarGroupOverflow.stories.tsx` | Default grouped overflow in LTR and RTL | Failing to mirror the Avatar-to-overflow order fails component-scoped RTL coverage. | `audit:AvatarGroupOverflow/i18n-rtl` |+| Documentation and surface | `AvatarGroupOverflow.doc.mjs`, block data tests, export checks, and `scripts/check-knowledge.mjs` | Consumer docs, blocks, package subpath, and this draft | Missing or stale docs, exports, required structure, relationships, or anatomy dispositions fail repository validation. | `audit:AvatarGroupOverflow/docs` |++Current audit scores, screenshots, eligibility, and per-run receipts remain in their+existing wiki, pull-request, and trusted-check owners rather than this contract.++## Decision log++None. This draft records current facts and introduces no component-local API,+behavior, accessibility, layout, theming, or design decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables or examples, current audit+scores or screenshots, implementation steps, AvatarGroup's focus algorithm, or+shared API, theming, knowledge, and audit-system rules. It links to their owners.diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx b/packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsxnew file mode 100644index 0000000000..206779bccb--- /dev/null+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx@@ -0,0 +1,241 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {AvatarGroup} from './AvatarGroup';+import {AvatarGroupOverflow} from './AvatarGroupOverflow';+import {Avatar} from '../Avatar';+import {InternationalizationProvider} from '../i18n';++describe('AvatarGroupOverflow', () => {+ it('renders overflow count as span by default', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={5} />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('5 more');+ expect(overflow.tagName).toBe('SPAN');+ expect(overflow).toHaveTextContent('+5');+ });++ it('applies the group size class to the overflow chip', () => {+ render(+ <AvatarGroup size="lg">+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={5} />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('5 more');+ expect(overflow.className).toContain('astryx-avatar-group-overflow');+ expect(overflow.className).toContain('lg');+ expect(overflow).toHaveAttribute('data-size', 'lg');+ });++ it('applies the group shape to the overflow chip, matching its avatars', () => {+ render(+ <AvatarGroup shape="square">+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={5} />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('5 more');+ expect(overflow).toHaveAttribute('data-shape', 'square');+ });++ it('defaults the overflow chip to circle shape with no explicit AvatarGroup shape', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={5} />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('5 more');+ expect(overflow).toHaveAttribute('data-shape', 'circle');+ });++ it('renders as button when onClick is provided', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} onClick={() => {}} />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('3 more');+ expect(overflow.tagName).toBe('BUTTON');+ });++ it('calls onClick when clicked', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();++ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} onClick={handleClick} />+ </AvatarGroup>,+ );++ await user.click(screen.getByLabelText('3 more'));+ expect(handleClick).toHaveBeenCalledOnce();+ });++ it('renders custom children instead of default label', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={5}>+ <span data-testid="custom">more</span>+ </AvatarGroupOverflow>+ </AvatarGroup>,+ );++ expect(screen.getByTestId('custom')).toBeInTheDocument();+ });++ it('works with sliced avatar list and server-side count', () => {+ const users = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];+ const serverTotal = 47;+ const visibleCount = 3;++ render(+ <AvatarGroup size="lg">+ {users.slice(0, visibleCount).map(name => (+ <Avatar key={name} name={name} />+ ))}+ <AvatarGroupOverflow count={serverTotal - visibleCount} />+ </AvatarGroup>,+ );++ expect(screen.getByLabelText('Alice')).toBeInTheDocument();+ expect(screen.getByLabelText('Bob')).toBeInTheDocument();+ expect(screen.getByLabelText('Charlie')).toBeInTheDocument();+ expect(screen.getByLabelText('44 more')).toBeInTheDocument();+ expect(screen.getByText('+44')).toBeInTheDocument();+ });++ it('forwards ref to the span element', () => {+ const ref = {current: null} as React.RefObject<HTMLElement | null>;++ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} ref={ref} />+ </AvatarGroup>,+ );++ expect(ref.current).toBeInstanceOf(HTMLSpanElement);+ });++ it('forwards ref to the button element when onClick provided', () => {+ const ref = {current: null} as React.RefObject<HTMLElement | null>;++ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} onClick={() => {}} ref={ref} />+ </AvatarGroup>,+ );++ expect(ref.current).toBeInstanceOf(HTMLButtonElement);+ });++ it('applies className prop', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} className="custom-class" />+ </AvatarGroup>,+ );++ const overflow = screen.getByLabelText('3 more');+ expect(overflow.className).toContain('custom-class');+ });++ it('handles count of zero gracefully', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={0} />+ </AvatarGroup>,+ );++ expect(screen.getByText('+0')).toBeInTheDocument();+ expect(screen.getByLabelText('0 more')).toBeInTheDocument();+ });++ it('clamps a negative count rather than rendering "+-3"', () => {+ // `count={total - visibleCount}` is the documented shape, and it goes+ // negative whenever the list is shorter than the slice.+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={-3} />+ </AvatarGroup>,+ );++ expect(screen.queryByText('+-3')).not.toBeInTheDocument();+ expect(screen.getByText('+0')).toBeInTheDocument();+ expect(screen.getByLabelText('0 more')).toBeInTheDocument();+ });++ it('renders outside an AvatarGroup at the md fallback size', () => {+ render(<AvatarGroupOverflow count={3} data-testid="loose" />);++ const overflow = screen.getByTestId('loose');+ expect(overflow).toHaveTextContent('+3');+ // inline-flex, so a standalone indicator stays a circle instead of+ // stretching to its parent's width.+ expect(overflow.tagName).toBe('SPAN');+ });++ it('handles very large count', () => {+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={999} />+ </AvatarGroup>,+ );++ expect(screen.getByText('+999')).toBeInTheDocument();+ });++ it('renders the full "+N" text for wide multi-digit counts', () => {+ // The indicator grows into a pill for long counts, so the entire number+ // must remain present (nothing clipped away in the DOM).+ render(+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={4912} />+ </AvatarGroup>,+ );++ expect(screen.getByText('+4912')).toBeInTheDocument();+ // The aria-label routes through the catalog's `{count, number}` ICU+ // argument, so the en locale adds a grouping separator.+ expect(screen.getByLabelText('4,912 more')).toBeInTheDocument();+ });++ it('localizes the overflow label through the i18n catalog', () => {+ render(+ <InternationalizationProvider+ locale="fr"+ overrides={{+ fr: {'@astryx.avatarGroup.overflow': '{count, number} de plus'},+ }}>+ <AvatarGroup>+ <Avatar name="Alice" />+ <AvatarGroupOverflow count={3} />+ </AvatarGroup>+ </InternationalizationProvider>,+ );++ expect(screen.getByLabelText('3 de plus')).toBeInTheDocument();+ });+});diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsxindex f5363d275e..9cbb602ad8 100644--- a/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.tsx@@ -10,6 +10,7 @@* SYNC: When modified, update these files to stay in sync:* - /packages/core/src/AvatarGroup/AvatarGroup.doc.mjs* - /packages/core/src/AvatarGroup/index.ts+ * - /apps/storybook/stories/AvatarGroupOverflow.stories.tsx* - /packages/cli/assets/templates/blocks/components/AvatarGroup/ (showcase blocks)*/