@astryxdesign/core 0.1.8 → 0.1.9-canary.75d2d03

package/dist/utils/plainDate.js

@@ -161,6 +161,15 @@ export const DATE_FORMAT_WITH_WEEKDAY = {
   day: 'numeric'
 };
 
+// e.g. "Wed, May 21, 2026" (locale-dependent) — short weekday + short month.
+// Backs the shared `date_weekday` format used by both Timestamp and DateInput.
+export const DATE_FORMAT_SHORT_WITH_WEEKDAY = {
+  weekday: 'short',
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric'
+};
+
 // e.g. "May 21, 2026" (locale-dependent)
 export const DATE_FORMAT_LONG = {
   year: 'numeric',
@@ -188,4 +197,48 @@ export const DATE_FORMAT_SHORT_WITH_YEAR = {
 };
 export function plainDateFormat(pd, options) {
   return new Intl.DateTimeFormat(undefined, options).format(plainDateToDate(pd));
+}
+
+// =============================================================================
+// Shared date-only format vocabulary
+// =============================================================================
+
+/**
+ * The date-only members of Timestamp's `format` vocabulary that a
+ * calendar-date field (no time-of-day) can render. Both Timestamp and
+ * DateInput share these string literals and the mapping below so that the same
+ * literal renders the same date shape in either component.
+ *
+ * - `date`: locale short-month date, e.g. "Mar 21, 2026"
+ * - `date_long`: locale long-month date, e.g. "March 21, 2026"
+ * - `date_weekday`: short weekday + short-month date, e.g. "Wed, Mar 21, 2026"
+ * - `system_date`: ISO 8601 calendar date, e.g. "2026-03-21"
+ */
+
+/**
+ * Intl option bags for the locale-aware shared date members. `system_date` is
+ * intentionally absent — it is emitted as a fixed ISO `YYYY-MM-DD` string, not
+ * via `Intl` — and is handled directly by {@link formatSharedDate}.
+ *
+ * This is the single source of truth consumed by both Timestamp's
+ * `formatTimestamp` switch and DateInput's display path, so the two never
+ * drift for the members they share.
+ */
+export const SHARED_DATE_FORMAT_OPTIONS = {
+  date: DATE_FORMAT_SHORT_WITH_YEAR,
+  date_long: DATE_FORMAT_LONG,
+  date_weekday: DATE_FORMAT_SHORT_WITH_WEEKDAY
+};
+
+/**
+ * Renders a {@link PlainDate} using one of the {@link SharedDateFormat}
+ * members. The shared entry point DateInput uses for the named-format path;
+ * Timestamp maps the same members onto {@link SHARED_DATE_FORMAT_OPTIONS} in
+ * its own `formatTimestamp` switch (its input is a `Date`, not a `PlainDate`).
+ */
+export function formatSharedDate(pd, format) {
+  if (format === 'system_date') {
+    return plainDateToISO(pd);
+  }
+  return plainDateFormat(pd, SHARED_DATE_FORMAT_OPTIONS[format]);
 }

package/dist/utils/types.d.ts

@@ -8,6 +8,19 @@
  * Size value type - accepts numbers (treated as pixels) or strings (e.g., '100%', '50vh').
  */
 export type SizeValue = number | string;
+/**
+ * Resting elevation level for configurable surfaces.
+ *
+ * Maps to the shadow token scale:
+ * - `none` = flat (`box-shadow: none`)
+ * - `low`  = `--shadow-low`
+ * - `med`  = `--shadow-med`
+ * - `high` = `--shadow-high`
+ *
+ * Components narrow this union to the steps they actually need — e.g. Card
+ * exposes all four, while ChatComposer exposes only `'none' | 'low'`.
+ */
+export type Elevation = 'none' | 'low' | 'med' | 'high';
 /**
  * Numeric spacing step from the Astryx spacing scale.
  *

package/dist/utils/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC"}

package/locales/en.json

@@ -263,6 +263,10 @@
     "defaultMessage": "Scroll right",
     "description": "Screen-reader-only label on the right arrow button in a Carousel. Pairs with `carousel.scrollLeft`; same RTL note."
   },
+  "@astryx.carousel.slideLabel": {
+    "defaultMessage": "Slide {current, number} of {total, number}",
+    "description": "Screen-reader accessible name for one slide in a Carousel, giving its position. `current` is the 1-based slide number; `total` is the slide count."
+  },
   "@astryx.chat.status.sending": {
     "defaultMessage": "Sending",
     "description": "Chat send-status caption under an outgoing message while it is being transmitted. Part of the set sending → sent → delivered → read (or failed) — keep tense/aspect consistent."
@@ -411,6 +415,10 @@
     "defaultMessage": "Select row",
     "description": "Aria label for the \"select row\" checkbox on a Table row."
   },
+  "@astryx.table.selection.selectRowNamed": {
+    "defaultMessage": "Select {label}",
+    "description": "Aria label for a Table row's selection checkbox when a per-row label is available (via getRowLabel). `label` is the row's human-readable identity, e.g. \"Alice\"."
+  },
   "@astryx.table.sort.ascending": {
     "defaultMessage": "Sort ascending",
     "description": "Screen-reader-only label on a column header button that will sort the column ascending. Part of a set with `sort.descending` and `sort.clear` — keep parallel."
@@ -679,6 +687,10 @@
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that removes the selected file from a FileInput. Example: `Clear Attachment`, `Clear Résumé`."
   },
+  "@astryx.fileInput.triggerWithFiles": {
+    "defaultMessage": "{label}, {fileNames}",
+    "description": "Accessible name for a FileInput trigger that has files attached, composing the field label with the selected filenames. Example: `Attachments, report.pdf, notes.txt`."
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "Media viewer",
     "description": "Screen-reader-only fallback name for the Lightbox dialog when the current media item has no alt text. Should rarely render — consumers should provide alt."
@@ -751,6 +763,14 @@
     "defaultMessage": "Expand row",
     "description": "Aria label for the Table tree-data expander chevron when the row is currently collapsed."
   },
+  "@astryx.tableTree.collapseAllRows": {
+    "defaultMessage": "Collapse all rows",
+    "description": "Aria label for the Table tree-data header toggle when all rows are expanded and clicking it collapses them."
+  },
+  "@astryx.tableTree.expandAllRows": {
+    "defaultMessage": "Expand all rows",
+    "description": "Aria label for the Table tree-data header toggle when rows are collapsed and clicking it expands them."
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a TextInput. Example: `Clear Email`, `Clear Name`."
@@ -763,6 +783,10 @@
     "defaultMessage": "Open {accessibleName}",
     "description": "\"Open\" = launch/reveal (not \"unfold\" or the adjective). Screen-reader-only name on a clickable Thumbnail — example: `Open Sunset photo`."
   },
+  "@astryx.thumbnail.fallbackName": {
+    "defaultMessage": "Thumbnail",
+    "description": "Generic screen-reader name for a Thumbnail (image preview) that has no `alt` or `label`. Last-resort fallback so the control is never nameless; prefer a real name via `alt` or `label`."
+  },
   "@astryx.timeInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a TimeInput. Example: `Clear Start time`."

package/locales/fr-FR.json

@@ -0,0 +1,14 @@
+{
+  "@astryx.pagination.previous": {
+    "defaultMessage": "Aller à la page précédente",
+    "description": "Aria label for the previous-page button."
+  },
+  "@astryx.pagination.next": {
+    "defaultMessage": "Aller à la page suivante",
+    "description": "Aria label for the next-page button."
+  },
+  "@astryx.selector.placeholder": {
+    "defaultMessage": "Sélectionner…",
+    "description": "Placeholder text on an empty Selector trigger button (a dropdown). Imperative verb; trailing `…` is one character. Very short — appears on the button face."
+  }
+}

package/locales/pseudo.json

@@ -197,6 +197,9 @@
   "@astryx.carousel.scrollRight": {
     "defaultMessage": "⟦Šçřółł říĝĥţ⟧"
   },
+  "@astryx.carousel.slideLabel": {
+    "defaultMessage": "⟦Šłíðé {current, number} óƒ {total, number}⟧"
+  },
   "@astryx.chat.status.sending": {
     "defaultMessage": "⟦Šéñðíñĝ⟧"
   },
@@ -308,6 +311,9 @@
   "@astryx.table.selection.selectRow": {
     "defaultMessage": "⟦Šéłéçţ řóŵ⟧"
   },
+  "@astryx.table.selection.selectRowNamed": {
+    "defaultMessage": "⟦Šéłéçţ {label}⟧"
+  },
   "@astryx.table.sort.ascending": {
     "defaultMessage": "⟦Šóřţ àšçéñðíñĝ⟧"
   },
@@ -509,6 +515,9 @@
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.fileInput.triggerWithFiles": {
+    "defaultMessage": "⟦{label}, {fileNames}⟧"
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "⟦Ṁéðíà ṽíéŵéř⟧"
   },
@@ -563,6 +572,12 @@
   "@astryx.tableTree.expandRow": {
     "defaultMessage": "⟦Éẋþàñð řóŵ⟧"
   },
+  "@astryx.tableTree.collapseAllRows": {
+    "defaultMessage": "⟦Çółłàþšé àłł řóŵš⟧"
+  },
+  "@astryx.tableTree.expandAllRows": {
+    "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
@@ -572,6 +587,9 @@
   "@astryx.thumbnail.open": {
     "defaultMessage": "⟦Óþéñ {accessibleName}⟧"
   },
+  "@astryx.thumbnail.fallbackName": {
+    "defaultMessage": "⟦Ţĥúɱƀñàíł⟧"
+  },
   "@astryx.timeInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.8",
+  "version": "0.1.9-canary.75d2d03",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",

package/src/AppShell/AppShell.tsx

@@ -24,6 +24,7 @@ import {
   isValidElement,
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -600,10 +601,14 @@ export function AppShell({
   // =========================================================================
   // Mobile context — shared with MobileNavToggle and future TopNav mobile
   // =========================================================================
+  // Stable id shared by the drawer (applied as its `id`) and the toggle
+  // (referenced via `aria-controls`) so screen readers know what it controls.
+  const mobileNavId = useId();
   const mobileContextValue = useMemo<AppShellMobileContextValue>(
     () => ({
       isMobile: isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       toggleMobileNav: () =>
         mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
       openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
@@ -614,6 +619,7 @@ export function AppShell({
     [
       isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       setMobileNavOpen,
       mobileNavEnabled,
       mobileNavHasToggle,

package/src/AppShell/AppShellMobileContext.tsx

@@ -20,6 +20,14 @@ export interface AppShellMobileContextValue {
   isMobile: boolean;
   /** Whether the mobile nav drawer is currently open */
   isMobileNavOpen: boolean;
+  /**
+   * DOM id of the mobile nav drawer. `AppShell` sets this so the toggle can
+   * point its `aria-controls` at the drawer and the drawer can apply it as its
+   * `id`. Optional: callers that construct this context by hand may omit it, in
+   * which case `MobileNav` falls back to a locally generated id and the toggle
+   * simply drops `aria-controls`.
+   */
+  mobileNavId?: string;
   /** Toggle the mobile nav drawer open/closed */
   toggleMobileNav: () => void;
   /** Open the mobile nav drawer */

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -31,6 +31,12 @@ export const docs = {
       description:
         'Whether the AppShell-managed mobile navigation drawer is open.',
     },
+    {
+      name: 'mobileNavId',
+      type: 'string | undefined',
+      description:
+        'DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer.',
+    },
     {
       name: 'toggleMobileNav',
       type: '() => void',
@@ -111,6 +117,8 @@ export const docsDense = {
     isMobile:
       'viewport below AppShell mobile nav breakpoint? Use to sync AppShell-adjacent mobile UI',
     isMobileNavOpen: 'AppShell-managed mobile nav drawer open?',
+    mobileNavId:
+      'DOM id of the drawer; point custom toggle aria-controls at it',
     toggleMobileNav: 'toggle drawer; no-op when mobile nav disabled',
     openMobileNav: 'open drawer; no-op when mobile nav disabled',
     closeMobileNav: 'close drawer',

package/src/Avatar/Avatar.doc.mjs

@@ -15,6 +15,7 @@ export const docs = {
       {guidance: true, description: 'Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.'},
       {guidance: true, description: 'Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.'},
       {guidance: true, description: 'Add a status dot when knowing someone\'s availability matters, like in chat or team views.'},
+      {guidance: true, description: 'When wrapping an Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
       {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular to stay consistent across the system.'},
     ],
@@ -22,13 +23,14 @@ export const docs = {
       {name: 'Photo', required: false, description: 'The profile image, loaded from the src URL. Shown when available.'},
       {name: 'Initials', required: false, description: 'One or two letters extracted from the name. Shown when no photo is available.'},
       {name: 'Default icon', required: false, description: 'A generic person silhouette. Shown when there is no photo or name.'},
-      {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy).'},
+      {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy). Each variant pairs colour with a distinct shape so status does not rely on colour alone.'},
     ],
   },
   theming: {
     targets: [
       {className: 'astryx-avatar', visualProps: ['size']},
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
+      {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
@@ -65,13 +67,21 @@ export const docs = {
       description: 'Corner content for status indicators.',
       slotElements: [
         {
-          __element: 'StatusDot',
+          __element: 'AvatarStatusDot',
           props: {
-            variant: 'online',
+            variant: 'success',
+            label: 'Online',
           },
         },
       ],
     },
+    {
+      name: 'tooltip',
+      type: 'string | boolean',
+      description:
+        "Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard — set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name.",
+      default: 'true',
+    },
   ],
   components: [
     {name: 'AvatarStatusDot'},
@@ -113,6 +123,8 @@ export const docsDense = {
     alt: 'alt text; falls back to name',
     size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
     status: 'corner content for status indicators',
+    tooltip:
+      "hover/focus tooltip. true/omitted → name; string → that text; false → none. Owns its tooltip; set false when wrapping in your own Tooltip/HoverCard. Default true.",
   },
   components: [
     {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},

package/src/Avatar/Avatar.test.tsx

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {Avatar} from './Avatar';
 
@@ -65,4 +65,159 @@ describe('Avatar', () => {
     expect(img).not.toBeNull();
     expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
   });
+
+  // --- Name tooltip (tooltip?: string | boolean) ---
+  describe('name tooltip', () => {
+    const originalShowPopover = HTMLElement.prototype.showPopover;
+    const originalHidePopover = HTMLElement.prototype.hidePopover;
+
+    beforeEach(() => {
+      // jsdom does not implement the Popover API the tooltip layer uses.
+      HTMLElement.prototype.showPopover = vi.fn();
+      HTMLElement.prototype.hidePopover = vi.fn();
+    });
+
+    afterEach(() => {
+      HTMLElement.prototype.showPopover = originalShowPopover;
+      HTMLElement.prototype.hidePopover = originalHidePopover;
+    });
+
+    it('shows the name in a tooltip by default', () => {
+      render(<Avatar name="Ada Lovelace" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Ada Lovelace');
+    });
+
+    it('shows a custom string tooltip instead of the name', () => {
+      render(<Avatar name="alovelace" tooltip="Ada Lovelace, Mathematician" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Ada Lovelace, Mathematician');
+      expect(tooltip).not.toHaveTextContent('alovelace');
+    });
+
+    it('renders no tooltip when tooltip={false}', () => {
+      render(<Avatar name="Ada Lovelace" tooltip={false} />);
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+    });
+
+    it('renders no tooltip for a decorative avatar (no name/alt)', () => {
+      render(<Avatar src="https://example.com/x.jpg" />);
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+    });
+
+    it('renders no tooltip when tooltip is true/default but name is empty', () => {
+      render(<Avatar name="   " alt="Profile photo" data-testid="a" />);
+      // A whitespace-only name yields nothing to show, and the default tooltip
+      // uses `name` (not `alt`), so there is no tooltip.
+      expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
+      // The accessible name still comes from alt, unaffected.
+      expect(
+        screen.getByRole('img', {name: 'Profile photo'}),
+      ).toBeInTheDocument();
+    });
+
+    it('still shows a custom string tooltip when there is no name', () => {
+      render(<Avatar tooltip="Anonymous user" data-testid="a" />);
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip).toHaveTextContent('Anonymous user');
+    });
+
+    it('makes the root focusable while a tooltip is attached', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" />);
+      expect(screen.getByTestId('a')).toHaveAttribute('tabindex', '0');
+    });
+
+    it('does not add a tab stop when the tooltip is disabled', () => {
+      render(<Avatar name="Ada Lovelace" tooltip={false} data-testid="a" />);
+      expect(screen.getByTestId('a')).not.toHaveAttribute('tabindex');
+    });
+
+    it('keeps the accessible name on the root regardless of the tooltip', () => {
+      const {rerender} = render(<Avatar name="Ada Lovelace" />);
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace'}),
+      ).toBeInTheDocument();
+
+      rerender(<Avatar name="Ada Lovelace" tooltip={false} />);
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace'}),
+      ).toBeInTheDocument();
+
+      rerender(<Avatar name="alovelace" tooltip="Ada Lovelace, Eng" />);
+      // alt||name still drives the accessible name — not the custom tooltip.
+      expect(screen.getByRole('img', {name: 'alovelace'})).toBeInTheDocument();
+
+      rerender(<Avatar name="alovelace" alt="Ada's profile photo" />);
+      expect(
+        screen.getByRole('img', {name: "Ada's profile photo"}),
+      ).toBeInTheDocument();
+    });
+
+    it('does not describe the root with the default name tooltip (no double-announce)', () => {
+      render(<Avatar name="Ada Lovelace" data-testid="a" />);
+      // The default name tooltip is visual-only: its text duplicates the root
+      // aria-label, so we deliberately do NOT wire aria-describedby (OQ-4).
+      expect(screen.getByTestId('a')).not.toHaveAttribute('aria-describedby');
+    });
+
+    it('describes the root with a custom string tooltip (matches Button)', () => {
+      render(
+        <Avatar
+          name="alovelace"
+          tooltip="Ada Lovelace, Mathematician"
+          data-testid="a"
+        />,
+      );
+      const root = screen.getByTestId('a');
+      const describedBy = root.getAttribute('aria-describedby');
+      expect(describedBy).toBeTruthy();
+      // aria-describedby points at the rendered tooltip layer.
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+      expect(tooltip.id).toBeTruthy();
+      expect(describedBy).toContain(tooltip.id);
+    });
+
+    it('composes a consumer aria-describedby with the custom tooltip description', () => {
+      render(
+        <>
+          <span id="extra-desc">extra description</span>
+          <Avatar
+            name="alovelace"
+            tooltip="Ada Lovelace, Eng"
+            aria-describedby="extra-desc"
+            data-testid="a"
+          />
+        </>,
+      );
+      const describedBy = screen
+        .getByTestId('a')
+        .getAttribute('aria-describedby');
+      expect(describedBy).toContain('extra-desc');
+    });
+
+    it('preserves a consumer aria-describedby with the default name tooltip', () => {
+      render(
+        <>
+          <span id="extra-desc">extra description</span>
+          <Avatar
+            name="Ada Lovelace"
+            aria-describedby="extra-desc"
+            data-testid="a"
+          />
+        </>,
+      );
+      // Default name tooltip does not touch aria-describedby, so the consumer
+      // value passes through untouched.
+      expect(screen.getByTestId('a')).toHaveAttribute(
+        'aria-describedby',
+        'extra-desc',
+      );
+    });
+
+    it('forwards the consumer ref to the root while a tooltip is attached', () => {
+      const ref = {current: null as HTMLDivElement | null};
+      render(<Avatar name="Ada Lovelace" ref={ref} data-testid="a" />);
+      expect(ref.current).toBe(screen.getByTestId('a'));
+    });
+  });
 });