@astryxdesign/core 0.3.0 → 0.4.0-canary.41f53a0

package/src/AppShell/AppShell.test.tsx

@@ -19,11 +19,13 @@ import {
   afterEach,
 } from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {AppShell} from './AppShell';
 import {InternationalizationProvider} from '../i18n';
 import {MobileNav} from '../MobileNav';
 import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
 import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
+import {useAppShellMobile} from './AppShellMobileContext';
 
 // jsdom doesn't implement showModal/close on <dialog>, so we mock them
 beforeAll(() => {
@@ -778,4 +780,141 @@ describe('AppShell', () => {
     expect(ref).toHaveBeenCalled();
     expect(ref.mock.calls[0][0]).toBe(screen.getByTestId('shell'));
   });
+  // ===========================================================================
+  // Keyboard operation
+  //
+  // The focus TRAP and focus RESTORE contracts of the drawer are native
+  // <dialog> behaviour and cannot be asserted here: jsdom has no dialog
+  // implementation, so this file shims showModal()/close() with an `open`
+  // attribute. Those two were verified in Chromium instead. What is asserted
+  // here is everything the shim can still prove: the keyboard path to each
+  // control, and the ARIA wiring between the toggle and the drawer.
+  // ===========================================================================
+
+  it('reaches the skip link with Tab and moves focus to main with Enter', async () => {
+    const user = userEvent.setup();
+    render(
+      <AppShell topNav={<TopNav label="Main navigation" />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    await user.tab();
+    const skipLink = screen.getByTestId('skip-to-content');
+    expect(skipLink).toHaveFocus();
+
+    await user.keyboard('{Enter}');
+    expect(screen.getByRole('main')).toHaveFocus();
+  });
+
+  it('opens the mobile drawer from the keyboard and points the toggle at it', async () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+    const user = userEvent.setup();
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Open navigation'});
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+    toggle.focus();
+    await user.keyboard('{Enter}');
+
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+    const drawer = screen.getByRole('dialog', {hidden: true});
+    // aria-controls has to name the drawer that actually opened, or a screen
+    // reader cannot follow the toggle to it.
+    expect(toggle.getAttribute('aria-controls')).toBe(drawer.id);
+    expect(drawer.id).toBeTruthy();
+  });
+
+  // ===========================================================================
+  // Banner landmark on the mobile top bar
+  // ===========================================================================
+
+  it('exposes the mobile top bar as a banner landmark in a sidenav-only layout', () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    // Same landmark structure as the topNav layout: one banner region holding
+    // the top bar, whichever nav slots the page happens to fill.
+    expect(screen.getByRole('banner')).toBeInTheDocument();
+  });
+
+  it('renders exactly one banner landmark when a banner slot joins the mobile top bar', () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+    render(
+      <AppShell banner={<div>Announcement</div>} sideNav={<TestSideNav />}>
+        <div>Content</div>
+      </AppShell>,
+    );
+
+    expect(screen.getAllByRole('banner')).toHaveLength(1);
+  });
+
+  // ===========================================================================
+  // useAppShellMobile
+  // ===========================================================================
+
+  function MobileProbe() {
+    const {isMobile, isMobileNavOpen, isMobileNavEnabled, mobileNavId} =
+      useAppShellMobile();
+    return (
+      <span data-testid="probe">
+        {JSON.stringify({
+          isMobile,
+          isMobileNavOpen,
+          isMobileNavEnabled,
+          hasId: mobileNavId != null,
+        })}
+      </span>
+    );
+  }
+
+  it('useAppShellMobile is inert outside an AppShell', () => {
+    render(<MobileProbe />);
+    expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+      isMobile: false,
+      isMobileNavOpen: false,
+      isMobileNavEnabled: false,
+      hasId: false,
+    });
+  });
+
+  it('useAppShellMobile reports the shell mobile state and drawer id', async () => {
+    mockMql = createMockMatchMedia(true);
+    vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+    const user = userEvent.setup();
+
+    render(
+      <AppShell sideNav={<TestSideNav />}>
+        <MobileProbe />
+      </AppShell>,
+    );
+
+    expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+      isMobile: true,
+      isMobileNavOpen: false,
+      isMobileNavEnabled: true,
+      hasId: true,
+    });
+
+    await user.click(screen.getByRole('button', {name: 'Open navigation'}));
+
+    expect(
+      JSON.parse(screen.getByTestId('probe').textContent).isMobileNavOpen,
+    ).toBe(true);
+  });
 });

package/src/AppShell/AppShell.tsx

@@ -51,6 +51,7 @@ import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
@@ -217,7 +218,7 @@ export interface AppShellProps extends BaseProps<HTMLDivElement> {
    * <AppShell mobileNav={{ hasToggle: false }}>
    *   <MobileNavToggle />
    * </AppShell>
-   * <AppShell mobileNav={<MobileNav title="Menu">...</MobileNav>} />
+   * <AppShell mobileNav={<MobileNav header="Menu">...</MobileNav>} />
    * <AppShell mobileNav={false} />
    * ```
    */
@@ -409,8 +410,8 @@ const styles = stylex.create({
     flexShrink: 0,
     overflow: 'clip',
     position: 'sticky',
-    top: 'var(--appshell-header-height, 0px)',
-    height: 'calc(100dvh - var(--appshell-header-height, 0px))',
+    top: 'var(--_app-shell-header-height, 0px)',
+    height: 'calc(100dvh - var(--_app-shell-header-height, 0px))',
     // Ensure children (LayoutPanel → SideNav) fill the sticky container
     display: 'flex',
     flexDirection: 'column',
@@ -441,7 +442,7 @@ const styles = stylex.create({
  *   topNav={<TopNav label="Navigation" heading={<TopNavHeading heading="My App" />} />}
  *   sideNav={<SideNav>{navSections}</SideNav>}
  *   mobileNav={
- *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} title="My App">
+ *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} header="My App">
  *       {navSections}
  *     </MobileNav>
  *   }>
@@ -512,14 +513,19 @@ export function AppShell({
   const [uncontrolledMobileOpen, setUncontrolledMobileOpen] = useState(false);
   const isMobileNavOpen = mobileNavConfig?.isOpen ?? uncontrolledMobileOpen;
 
+  const mobileNavOnOpenChange = mobileNavConfig?.onOpenChange;
   const setMobileNavOpen = useCallback(
     (open: boolean) => {
       if (!mobileNavIsControlled) {
         setUncontrolledMobileOpen(open);
       }
-      mobileNavConfig?.onOpenChange?.(open);
+      mobileNavOnOpenChange?.(open);
     },
-    [mobileNavIsControlled, mobileNavConfig],
+    // Depend on the callback itself, not on the config object: the documented
+    // usage is an inline `mobileNav={{isOpen, onOpenChange}}` literal, which is
+    // a new object every render and would otherwise churn this callback and the
+    // context value memo built from it on every render of the shell.
+    [mobileNavIsControlled, mobileNavOnOpenChange],
   );
 
   // Move focus to the main content container when the skip link is activated.
@@ -577,7 +583,7 @@ export function AppShell({
 
     const updateHeight = () => {
       const height = headerEl.getBoundingClientRect().height;
-      shellEl.style.setProperty('--appshell-header-height', `${height}px`);
+      shellEl.style.setProperty('--_app-shell-header-height', `${height}px`);
     };
 
     observeResize(headerEl, () => updateHeight());
@@ -669,20 +675,19 @@ export function AppShell({
       </LayoutHeader>
     ) : undefined;
 
-  const headerContent =
-    headerInner != null ? (
-      <div
-        ref={headerRef}
-        // Top-level banner landmark for the header region (topNav + banner).
-        // Safe here: the wrapper is never nested inside main/nav/other landmarks.
-        role="banner"
-        {...mergeProps(
-          themeProps('app-shell-header', {variant}),
-          stylex.props(navAreaStyle, isAuto && styles.headerSticky),
-        )}>
-        {headerInner}
-      </div>
-    ) : undefined;
+  const headerContent = isRenderable(headerInner) ? (
+    <div
+      ref={headerRef}
+      // Top-level banner landmark for the header region (topNav + banner).
+      // Safe here: the wrapper is never nested inside main/nav/other landmarks.
+      role="banner"
+      {...mergeProps(
+        themeProps('app-shell-header', {variant}),
+        stylex.props(navAreaStyle, isAuto && styles.headerSticky),
+      )}>
+      {headerInner}
+    </div>
+  ) : undefined;
 
   // =========================================================================
   // Build sideNav content
@@ -760,6 +765,11 @@ export function AppShell({
   const autoMobileTopBar =
     shouldShowAutoToggle && !hasTopNav && hasSideNav ? (
       <div
+        // Banner landmark for the mobile top bar, so the sidenav-only layout
+        // exposes the same landmark structure as the topNav one. Only when
+        // there is no headerContent: a banner slot with no topNav renders both,
+        // and two sibling banner regions is worse than the one this restores.
+        role={headerContent == null ? 'banner' : undefined}
         {...mergeProps(
           themeProps('app-shell-header', {variant}),
           stylex.props(navAreaStyle, isAuto && styles.headerSticky),
@@ -805,7 +815,7 @@ export function AppShell({
         <a
           href={`#${MAIN_CONTENT_ID}`}
           onClick={handleSkipLinkClick}
-          {...stylex.props(styles.skipLink)}
+          {...focusOutlineProps.focusVisible(styles.skipLink)}
           data-testid="skip-to-content">
           {t('@astryx.appShell.skipToContent')}
         </a>

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -9,13 +9,21 @@ export const docs = {
   keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -68,13 +76,21 @@ export const docsZh = {
   displayName: 'Aspect Ratio',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -110,13 +126,21 @@ export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   propDescriptions: {

package/src/AspectRatio/AspectRatio.test.tsx

@@ -276,6 +276,36 @@ describe('AspectRatio', () => {
     });
   });
 
+  describe('style merging', () => {
+    it('keeps the consumer style and applies the ratio over it', () => {
+      render(
+        <AspectRatio
+          ratio={16 / 9}
+          data-testid="aspect-ratio"
+          style={{opacity: 0.5, aspectRatio: '3 / 1'}}>
+          <div>Content</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      expect(element.style.opacity).toBe('0.5');
+      expect(element.style.aspectRatio).toBe(String(16 / 9));
+    });
+
+    it('keeps a consumer className beside the theme target', () => {
+      render(
+        <AspectRatio
+          ratio={1}
+          data-testid="aspect-ratio"
+          className="consumer-class">
+          <div>Content</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      expect(element).toHaveClass('consumer-class');
+      expect(element).toHaveClass('astryx-aspect-ratio');
+    });
+  });
+
   describe('reset.css fit baseline rules', () => {
     // The cover/contain child sizing ships as zero-specificity baseline
     // rules in reset.css keyed on the data-astryx-aspect-ratio-override

package/src/AspectRatio/AspectRatio.tsx

@@ -94,6 +94,10 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   /**
    * Content to render inside the aspect ratio container.
    * The child element will be positioned absolutely to fill the container.
+   *
+   * Pass a single child. With `fit` set, every direct child is stretched to
+   * fill the box, so a second child is laid out below the first and clipped
+   * out of view; compose an overlay or caption inside one wrapper child.
    */
   children: ReactNode;
 }
@@ -145,6 +149,15 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * Sizing: the box takes its width from its container and derives its height
+ * from the ratio, so it needs an ancestor with a definite width. Two
+ * consequences are worth knowing. Constraining only the height (`height` or
+ * `maxHeight`) clamps the box without releasing the width, so the rendered
+ * ratio no longer matches `ratio`; pass `width: 'auto'` alongside to size from
+ * the height instead. And in a shrink-to-fit parent (`inline-flex`,
+ * `width: fit-content`, a floated box) it contributes no intrinsic width and
+ * collapses to zero.
+ *
  * @example
  * ```
  * <AspectRatio ratio={16 / 9} fit="cover">

package/src/Avatar/Avatar.doc.mjs

@@ -29,21 +29,10 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-avatar', visualProps: ['size']},
+      {className: 'astryx-avatar-fallback', visualProps: ['size']},
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
       {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
-    vars: [
-      {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},
-      {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},
-      {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},
-      {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},
-    ],
-    derived: [
-      {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
-      {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
-      {property: 'color', vars: ['--_avatar-fallback-color']},
-      {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
-    ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
   props: [
@@ -104,7 +93,7 @@ export const docs = {
       name: 'as',
       type: 'ElementType',
       description:
-        'Custom link component used when `href` is set (e.g. Next.js `Link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
+        'Custom link component used when `href` is set (e.g. `next/link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
     },
     {
       name: 'target',

package/src/Avatar/Avatar.test.tsx

@@ -37,17 +37,42 @@ describe('Avatar', () => {
     expect(innerImg).toHaveAttribute('alt', '');
   });
 
-  it('renders fallback initials through the themeable font-size var, not a bare px literal', () => {
+  it('renders fallback initials at the proportional size via a StyleX class, not an inline property', () => {
     render(<Avatar name="Ada Lovelace" size="sm" data-testid="a" />);
     const initials = screen.getByText('AL');
-    // The seam: the dynamic font size resolves to the Avatar-scoped var (with
-    // the proportional `size × 0.4` default baked in as the fallback), so a
-    // theme can re-scope it per size. A regression to a bare px literal would
-    // break theming.
+    // The default proportional size (sm = 24 × 0.4 = 9.6px) is fed to StyleX as
+    // a dynamic value: StyleX applies `font-size` through a class and sets only
+    // the computed value inline (as a custom property). Because the property
+    // lands via a class, a theme's `.astryx-avatar-fallback.<size>` rule in the
+    // theme layer overrides it per size tier — no internal var seam needed.
     const style = initials.getAttribute('style') ?? '';
-    expect(style).toContain('var(--_avatar-fallback-font-size,');
-    // Default still reproduces the proportional scale (sm = 24 × 0.4 = 9.6px).
-    expect(style).toMatch(/var\(--_avatar-fallback-font-size,\s*9\.6\d*px\)/);
+    expect(style).toMatch(/9\.6\d*px/);
+    // Regression guard: the seam must NOT reintroduce the removed internal var.
+    expect(style).not.toContain('--_avatar-fallback-font-size');
+  });
+
+  it('marks the fallback surface with the stable theming class (initials and icon)', () => {
+    // The background is themed directly on `.astryx-avatar-fallback`, so both
+    // the initials and the default-icon fallback must carry the class.
+    const {rerender} = render(<Avatar name="Ada Lovelace" />);
+    expect(screen.getByText('AL').className).toContain(
+      'astryx-avatar-fallback',
+    );
+
+    rerender(<Avatar />);
+    const icon = document.querySelector('.astryx-avatar-fallback');
+    expect(icon).not.toBeNull();
+    expect(icon?.querySelector('svg')).not.toBeNull();
+  });
+
+  it('does not split an emoji surrogate pair when generating initials', () => {
+    render(<Avatar name="😀 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('😀A');
+  });
+
+  it('preserves a complete grapheme when generating initials', () => {
+    render(<Avatar name="🇬🇧 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('🇬🇧A');
   });
 
   it('retries a new src after a previous src failed to load', () => {