An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file AppShell.test.tsx
* @input Uses vitest, React server rendering, @testing-library/react, AppShell component
* @output Unit tests for AppShell client behavior and SSR breakpoint semantics
* @position Testing; validates AppShell.tsx implementation
*
* SYNC: When AppShell.tsx changes, update tests to match new behavior
*/
import {
describe,
it,
expect,
vi,
beforeAll,
beforeEach,
afterEach,
} from 'vitest';
import {use} from 'react';
import {renderToString} from 'react-dom/server';
import {act, render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {AppShell} from './AppShell';
import {Card} from '../Card/Card';
import {Section} from '../Section/Section';
import {LayoutAreaContext} from '../Layout/LayoutAreaContext';
import {
DEFAULT_LAYOUT_SLOTS,
LayoutSlotsContext,
} from '../Layout/LayoutSlotsContext';
import {Layout} from '../Layout/Layout';
import {LayoutHeader} from '../Layout/LayoutHeader';
import {InternationalizationProvider} from '../i18n';
import {MobileNav} from '../MobileNav';
import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
import {TextInput} from '../TextInput';
import {useAppShellMobile} from './AppShellMobileContext';
import {Theme, defineTheme} from '../theme';
// jsdom doesn't implement showModal/close on <dialog>, so we mock them
beforeAll(() => {
HTMLDialogElement.prototype.showModal =
HTMLDialogElement.prototype.showModal ||
function (this: HTMLDialogElement) {
this.setAttribute('open', '');
};
HTMLDialogElement.prototype.close =
HTMLDialogElement.prototype.close ||
function (this: HTMLDialogElement) {
this.removeAttribute('open');
};
});
// Mock ResizeObserver
class MockResizeObserver {
callback: ResizeObserverCallback;
constructor(callback: ResizeObserverCallback) {
this.callback = callback;
}
observe() {}
unobserve() {}
disconnect() {}
}
vi.stubGlobal('ResizeObserver', MockResizeObserver);
// Helper: minimal SideNav that provides the navigation landmark
function TestSideNav({children}: {children?: React.ReactNode}) {
return (
<SideNav>
<SideNavSection title="Test" isHeaderHidden>
<SideNavItem label={typeof children === 'string' ? children : 'Nav'} />
</SideNavSection>
</SideNav>
);
}
// Mock matchMedia
function createMockMatchMedia(matches: boolean) {
const listeners: ((e: MediaQueryListEvent) => void)[] = [];
const mql = {
matches,
media: '',
onchange: null,
addEventListener: vi.fn(
(_event: string, handler: (e: MediaQueryListEvent) => void) => {
listeners.push(handler);
},
),
removeEventListener: vi.fn(
(_event: string, handler: (e: MediaQueryListEvent) => void) => {
const idx = listeners.indexOf(handler);
if (idx >= 0) {
listeners.splice(idx, 1);
}
},
),
addListener: vi.fn(),
removeListener: vi.fn(),
dispatchEvent: vi.fn(),
// Expose for test control
_listeners: listeners,
_setMatches: (newMatches: boolean) => {
mql.matches = newMatches;
for (const listener of listeners) {
listener({matches: newMatches} as MediaQueryListEvent);
}
},
};
return mql;
}
let mockMql: ReturnType<typeof createMockMatchMedia>;
beforeEach(() => {
mockMql = createMockMatchMedia(false);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
});
afterEach(() => {
vi.restoreAllMocks();
act(() => {
document.documentElement.removeAttribute('data-astryx-theme');
});
});
describe('AppShell', () => {
// ===========================================================================
// Basic rendering
// ===========================================================================
it('renders children as main content', () => {
render(
<AppShell>
<div>Main content</div>
</AppShell>,
);
expect(screen.getByText('Main content')).toBeInTheDocument();
});
it('renders main element with role="main"', () => {
render(
<AppShell>
<div>Content</div>
</AppShell>,
);
expect(screen.getByRole('main')).toBeInTheDocument();
});
it('renders topNav in the header area', () => {
render(
<AppShell topNav={<div>Top Nav</div>}>
<div>Content</div>
</AppShell>,
);
expect(screen.getByText('Top Nav')).toBeInTheDocument();
});
it('renders banner when provided', () => {
render(
<AppShell banner={<div>System banner</div>}>
<div>Content</div>
</AppShell>,
);
expect(screen.getByText('System banner')).toBeInTheDocument();
});
it('renders sideNav in a nav element', () => {
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
const nav = screen.getByRole('navigation');
expect(nav).toBeInTheDocument();
expect(screen.getByText('Nav')).toBeInTheDocument();
});
it('renders without optional slots', () => {
render(
<AppShell>
<div>Just content</div>
</AppShell>,
);
expect(screen.getByText('Just content')).toBeInTheDocument();
expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
});
it('supports data-testid', () => {
render(
<AppShell data-testid="my-shell">
<div>Content</div>
</AppShell>,
);
expect(screen.getByTestId('my-shell')).toBeInTheDocument();
});
// ===========================================================================
// Skip-to-content link
// ===========================================================================
it('renders a skip-to-content link', () => {
render(
<AppShell>
<div>Content</div>
</AppShell>,
);
const skipLink = screen.getByTestId('skip-to-content');
expect(skipLink).toBeInTheDocument();
expect(skipLink).toHaveAttribute('href', '#astryx-app-shell-main');
expect(skipLink.textContent).toBe('Skip to content');
});
it('main content has the correct id for skip link', () => {
render(
<AppShell>
<div>Content</div>
</AppShell>,
);
const main = screen.getByRole('main');
expect(main).toHaveAttribute('id', 'astryx-app-shell-main');
});
it('moves focus to the main content when the skip link is activated', () => {
render(
<AppShell>
<div>Content</div>
</AppShell>,
);
const skipLink = screen.getByTestId('skip-to-content');
const main = screen.getByRole('main');
// The target must be programmatically focusable for focus to move
expect(main).toHaveAttribute('tabindex', '-1');
fireEvent.click(skipLink);
expect(document.activeElement).toBe(main);
});
it('gives a second shell its own main id; the first keeps the fixed id', () => {
const view = render(
<div>
<AppShell key="first">
<div>First</div>
</AppShell>
<AppShell key="second">
<div>Second</div>
</AppShell>
</div>,
);
const [firstMain, secondMain] = screen.getAllByRole('main');
const [firstSkip, secondSkip] = screen.getAllByTestId('skip-to-content');
expect(firstMain).toHaveAttribute('id', 'astryx-app-shell-main');
expect(secondMain.id).not.toBe('astryx-app-shell-main');
expect(secondMain.id).not.toBe('');
expect(document.querySelectorAll(`[id="${secondMain.id}"]`)).toHaveLength(
1,
);
expect(firstSkip).toHaveAttribute('href', '#astryx-app-shell-main');
expect(secondSkip).toHaveAttribute('href', `#${secondMain.id}`);
fireEvent.click(secondSkip);
expect(document.activeElement).toBe(secondMain);
// When the first shell leaves, the remaining shell takes the fixed id.
view.rerender(
<div>
<AppShell key="second">
<div>Second</div>
</AppShell>
</div>,
);
expect(screen.getByRole('main')).toHaveAttribute(
'id',
'astryx-app-shell-main',
);
});
it('keeps the fixed id on the page shell when another shell is nested in its content', () => {
render(
<AppShell data-testid="outer">
<AppShell data-testid="inner">
<div>Nested</div>
</AppShell>
</AppShell>,
);
const outerMain = screen
.getByTestId('outer')
.querySelector<HTMLElement>(':scope [role="main"]');
const innerMain = screen
.getByTestId('inner')
.querySelector<HTMLElement>('[role="main"]');
expect(outerMain).toHaveAttribute('id', 'astryx-app-shell-main');
expect(innerMain?.id).not.toBe('astryx-app-shell-main');
expect(innerMain?.id).not.toBe('');
});
it('skip link text comes from the i18n catalog', () => {
render(
<InternationalizationProvider
locale="en"
overrides={{en: {'@astryx.appShell.skipToContent': 'Jump to main'}}}>
<AppShell>
<div>Content</div>
</AppShell>
</InternationalizationProvider>,
);
expect(screen.getByTestId('skip-to-content').textContent).toBe(
'Jump to main',
);
});
// ===========================================================================
// Banner landmark
// ===========================================================================
it('exposes the header region as a banner landmark', () => {
render(
<AppShell topNav={<div>Top Nav</div>}>
<div>Content</div>
</AppShell>,
);
const banner = screen.getByRole('banner');
expect(banner).toBeInTheDocument();
// banner must be top-level — not nested inside another landmark
expect(screen.getByRole('main')).not.toContainElement(banner);
});
it('does not render a banner landmark without header content', () => {
render(
<AppShell>
<div>Content</div>
</AppShell>,
);
expect(screen.queryByRole('banner')).not.toBeInTheDocument();
});
// ===========================================================================
// SideNav accessibility
// ===========================================================================
it('sideNav has aria-label', () => {
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
const nav = screen.getByRole('navigation');
expect(nav).toHaveAttribute('aria-label', 'Side navigation');
});
// ===========================================================================
// SideNav collapse — uncontrolled
// ===========================================================================
it('sideNav is visible by default (uncontrolled)', () => {
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
expect(screen.getByText('Nav')).toBeInTheDocument();
expect(screen.getByRole('navigation')).toBeInTheDocument();
});
// (Collapse tests removed — collapse is now managed by SideNav, not AppShell)
// ===========================================================================
// Responsive breakpoint
// ===========================================================================
it('preserves input value and focus across mobile breakpoints.', async () => {
const user = userEvent.setup();
render(
<AppShell
variant="elevated"
topNav="Top navigation"
sideNav="Side navigation"
mobileNav={{breakpoint: 'md'}}>
<input aria-label="Page draft" />
</AppShell>,
);
await user.type(
screen.getByRole('textbox', {name: 'Page draft'}),
'Keep this draft',
);
for (const isMobile of [true, false]) {
act(() => mockMql._setMatches(isMobile));
const input = screen.getByRole('textbox', {name: 'Page draft'});
expect(input).toHaveValue('Keep this draft');
expect(input).toHaveFocus();
}
});
it('uses the default named breakpoint with an exclusive upper edge', () => {
render(
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 768px)');
});
it('resolves all named points through the nearest Theme', () => {
const theme = {
...defineTheme({
name: 'app-shell-points',
adaptations: {widthBreakpoints: {xl: 1400, '2xl': 1800}},
}),
__built: true as const,
};
render(
<Theme theme={theme}>
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: '2xl'}}>
<div>Content</div>
</AppShell>
</Theme>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 1800px)');
});
it('uses the provider object when another theme shares its name', () => {
const outer = {
...defineTheme({
name: 'same-name',
adaptations: {widthBreakpoints: {md: 700}},
}),
__built: true as const,
};
const inner = {
...defineTheme({
name: 'same-name',
adaptations: {widthBreakpoints: {md: 900}},
}),
__built: true as const,
};
render(
<Theme theme={outer}>
<Theme theme={inner}>
<div>Nested</div>
</Theme>
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>
</Theme>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 700px)');
});
it('uses a built theme object from provider context', () => {
const builtTheme = {
...defineTheme({
name: 'built-app-shell-points',
adaptations: {widthBreakpoints: {'2xl': 1700}},
}),
__built: true as const,
__adaptationRules: undefined,
};
render(
<Theme theme={builtTheme}>
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: '2xl'}}>
<div>Content</div>
</AppShell>
</Theme>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 1700px)');
});
it('falls back per key when built metadata has a partial width map', () => {
const partialBuiltTheme = {
...defineTheme({name: 'partial-built-app-shell-points'}),
__built: true as const,
__adaptations: {
widthBreakpoints: {md: 700},
rules: [],
},
} as unknown as ReturnType<typeof defineTheme>;
render(
<Theme theme={partialBuiltTheme}>
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'xl'}}>
<div>Content</div>
</AppShell>
</Theme>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 1280px)');
});
it('follows the registered root theme without provider context', () => {
defineTheme({
name: 'root-app-shell-points',
adaptations: {widthBreakpoints: {lg: 1111}},
});
const originalGetAttribute = document.documentElement.getAttribute.bind(
document.documentElement,
);
vi.spyOn(document.documentElement, 'getAttribute').mockImplementation(
name =>
name === 'data-astryx-theme'
? 'root-app-shell-points'
: originalGetAttribute(name),
);
render(
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'lg'}}>
<div>Content</div>
</AppShell>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 1111px)');
});
it('supports the added xl breakpoint without a Theme provider', () => {
render(
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'xl'}}>
<div>Content</div>
</AppShell>,
);
expect(window.matchMedia).toHaveBeenCalledWith('(width < 1280px)');
});
it('does not enter mobile mode when mobileNav breakpoint is none', () => {
render(
<AppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'none'}}>
<div>Content</div>
</AppShell>,
);
// breakpoint 'none' uses (width < 0px), which never matches,
// so sideNav stays inline and no mobile nav toggle appears
expect(screen.getByText('Nav')).toBeInTheDocument();
expect(
screen.queryByRole('button', {name: /menu/i}),
).not.toBeInTheDocument();
});
it('renders breakpoint none as non-mobile on the server regardless of the SSR hint', () => {
const host = document.createElement('div');
host.innerHTML = renderToString(
<AppShell
sideNav={<TestSideNav />}
mobileNav={{breakpoint: 'none', defaultIsMobile: true}}>
<div>Content</div>
</AppShell>,
);
expect(
host.querySelector(
'.astryx-app-shell > .astryx-layout .astryx-layout-panel',
),
).not.toBeNull();
});
// ===========================================================================
// Mobile overlay (default MobileNav wrapping sideNav)
// ===========================================================================
it('shows default mobile nav when below breakpoint and not collapsed', () => {
// Start below breakpoint with sideNav expanded
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
// Should show default mobile nav (MobileNav wrapping sideNav)
expect(screen.getByRole('dialog', {hidden: true})).toBeInTheDocument();
// Should show nav content inside the mobile nav
expect(screen.getByText('Nav')).toBeInTheDocument();
});
it('renders default mobile nav when below breakpoint', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
// Default mobile nav should be rendered when below breakpoint
expect(screen.getByRole('dialog', {hidden: true})).toBeInTheDocument();
});
it('keeps TopNav children in the combined mobile drawer with sideNav content', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
topNav={
<TopNav label="Navigation" heading={<TopNavHeading heading="App" />}>
<TopNavItem label="Home" href="/" />
</TopNav>
}
sideNav={<TestSideNav>Side item</TestSideNav>}>
<div>Content</div>
</AppShell>,
);
expect(
screen.getByRole('button', {name: /open navigation/i}),
).toBeInTheDocument();
expect(
screen.getAllByRole('dialog', {hidden: true}).length,
).toBeGreaterThan(0);
expect(screen.getByText('Home')).toBeInTheDocument();
expect(screen.getAllByText('Side item').length).toBeGreaterThan(0);
});
it('shows mobile nav toggle for sideNav-only layout with heading-only topNav (#2243)', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
topNav={
<TopNav
label="Main navigation"
heading={<TopNavHeading heading="My App" />}
/>
}
sideNav={<TestSideNav>Home</TestSideNav>}
mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>,
);
expect(
screen.getByRole('button', {name: /open navigation/i}),
).toBeInTheDocument();
});
it('renders sidenav items exactly once in mobile drawer when topNav has only heading (#2243)', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
variant="section"
topNav={
<TopNav
label="Main navigation"
heading={<TopNavHeading heading="My App" />}
/>
}
sideNav={
<SideNav>
<SideNavItem label="Dashboard" href="/" isSelected />
<SideNavItem label="Settings" href="/settings" />
</SideNav>
}
mobileNav={{breakpoint: 'md'}}
contentPadding={4}>
<div>Content</div>
</AppShell>,
);
expect(
screen.getByRole('button', {name: /open navigation/i}),
).toBeInTheDocument();
expect(screen.getAllByText('Dashboard')).toHaveLength(1);
expect(screen.getAllByText('Settings')).toHaveLength(1);
});
it('does not show auto mobile toggle when sideNav is explicitly undefined (#2243)', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
topNav={
<TopNav
label="Main navigation"
heading={<TopNavHeading heading="My App" />}
/>
}
sideNav={undefined}
mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>,
);
expect(
screen.queryByRole('button', {name: /open navigation/i}),
).not.toBeInTheDocument();
});
it('does not show auto mobile toggle when sideNav is omitted entirely', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
topNav={
<TopNav
label="Main navigation"
heading={<TopNavHeading heading="My App" />}
/>
}
mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>,
);
expect(
screen.queryByRole('button', {name: /open navigation/i}),
).not.toBeInTheDocument();
});
it('heading-only topNav does not prevent sidenav from collapsing to mobile (#2243)', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
const {container} = render(
<AppShell
topNav={
<TopNav
label="Main navigation"
heading={<TopNavHeading heading="My App" />}
/>
}
sideNav={<TestSideNav>Home</TestSideNav>}
mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</AppShell>,
);
const inlinePanel = container.querySelector('.astryx-layout-panel');
expect(inlinePanel).toBeNull();
});
it('renders mobile layout on first render when defaultIsMobile is true', () => {
// matchMedia says mobile too — simulates correct SSR hint
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
const {container} = render(
<AppShell sideNav={<TestSideNav />} mobileNav={{defaultIsMobile: true}}>
<div>Content</div>
</AppShell>,
);
// SideNav should NOT be rendered inline — it's in the mobile drawer
const inlinePanel = container.querySelector(
'.astryx-app-shell > .astryx-layout .astryx-layout-panel',
);
expect(inlinePanel).toBeNull();
});
// ===========================================================================
// Height modes
// ===========================================================================
it('defaults to fill mode', () => {
render(
<AppShell data-testid="shell">
<div>Content</div>
</AppShell>,
);
// The root element should exist (fill is default)
expect(screen.getByTestId('shell')).toBeInTheDocument();
});
it('supports auto height mode', () => {
render(
<AppShell height="auto" data-testid="shell">
<div>Content</div>
</AppShell>,
);
expect(screen.getByTestId('shell')).toBeInTheDocument();
});
it('renders topNav in auto mode', () => {
render(
<AppShell height="auto" topNav={<div>Nav</div>} data-testid="shell">
<div>Content</div>
</AppShell>,
);
expect(screen.getByText('Nav')).toBeInTheDocument();
});
// ===========================================================================
// Sticky navigation in auto mode
// ===========================================================================
// A Field input wrapper carries a local z-index (it paints above the
// attached status message box via a negative-margin overlap), so without a
// component-owned isolation boundary it competes with page-level stacking —
// a field scrolled underneath the sticky header then paints over it (#5689).
// The fix is local containment: the Field root isolates the wrapper's local
// layer, so the header needs no escalated z-index to stay above it. This
// asserts that ownership boundary — the field's painted surface is an
// isolated stacking context — not a comparison between two page-level
// z-index values.
it('contains Field input stacking locally so the sticky header needs no escalated z-index in auto mode', () => {
render(
<AppShell height="auto" topNav={<div>Nav</div>}>
<TextInput
label="Name"
statusVariant="detached"
value=""
onChange={() => {}}
/>
</AppShell>,
);
const header = screen.getByRole('banner');
const inputWrapper = screen.getByRole('textbox').parentElement!;
// The detached variant renders the input wrapper outside Field's isolated
// attached-status wrapper, so the Field root must own the boundary.
const fieldRoot = inputWrapper.parentElement!;
expect(inputWrapper).toBeTruthy();
expect(getComputedStyle(header).position).toBe('sticky');
// The header stays at its normal local stacking level — no escalation.
expect(Number(getComputedStyle(header).zIndex)).toBe(1);
expect(getComputedStyle(inputWrapper).position).toBe('relative');
// Field's local layers cannot escape into page-level stacking: the root
// establishes an isolation boundary around the input wrapper's z-index.
expect(getComputedStyle(fieldRoot).isolation).toBe('isolate');
});
it('wraps header in sticky container in auto mode', () => {
render(
<AppShell
height="auto"
topNav={<div data-testid="topnav">Nav</div>}
data-testid="shell">
<div>Content</div>
</AppShell>,
);
const topNav = screen.getByTestId('topnav');
// The sticky wrapper is the parent of the LayoutHeader div
// topNav -> LayoutHeader div -> sticky wrapper div
const headerWrapper = topNav.parentElement?.parentElement;
expect(headerWrapper).toBeTruthy();
expect(
headerWrapper?.style.position ||
getComputedStyle(headerWrapper!).position,
).toBeDefined();
});
it('renders an opaque section header only in auto mode', () => {
const {rerender} = render(
<AppShell height="auto" variant="section" topNav={<div>Nav</div>}>
<div>Content</div>
</AppShell>,
);
expect(
getComputedStyle(screen.getByRole('banner')).backgroundColor,
).not.toBe('rgba(0, 0, 0, 0)');
rerender(
<AppShell height="fill" variant="section" topNav={<div>Nav</div>}>
<div>Content</div>
</AppShell>,
);
expect(getComputedStyle(screen.getByRole('banner')).backgroundColor).toBe(
'rgba(0, 0, 0, 0)',
);
});
it('does not apply sticky wrapper in fill mode', () => {
render(
<AppShell
height="fill"
topNav={<div data-testid="topnav">Nav</div>}
data-testid="shell">
<div>Content</div>
</AppShell>,
);
// In fill mode, header still renders but without sticky wrapper styles
expect(screen.getByTestId('topnav')).toBeInTheDocument();
});
it('wraps sideNav in sticky container in auto mode', () => {
render(
<AppShell
height="auto"
topNav={<div>Nav</div>}
sideNav={<div data-testid="sidenav">Side</div>}
data-testid="shell">
<div>Content</div>
</AppShell>,
);
expect(screen.getByTestId('sidenav')).toBeInTheDocument();
// The sideNav should be wrapped in a sticky div in auto mode
const sideNav = screen.getByTestId('sidenav');
// sideNav -> LayoutPanel div -> sticky wrapper div
const stickyWrapper = sideNav.parentElement?.parentElement;
expect(stickyWrapper).toBeTruthy();
});
it('sets up ResizeObserver on header in auto mode', () => {
const observeSpy = vi.fn();
const disconnectSpy = vi.fn();
vi.stubGlobal(
'ResizeObserver',
class {
constructor(public callback: ResizeObserverCallback) {}
observe = observeSpy;
unobserve = vi.fn();
disconnect = disconnectSpy;
},
);
render(
<AppShell height="auto" topNav={<div>Nav</div>} data-testid="shell">
<div>Content</div>
</AppShell>,
);
expect(observeSpy).toHaveBeenCalled();
});
it('does not observe the header in fill mode', () => {
const observeSpy = vi.fn();
vi.stubGlobal(
'ResizeObserver',
class {
constructor(public callback: ResizeObserverCallback) {}
observe = observeSpy;
unobserve = vi.fn();
disconnect = vi.fn();
},
);
render(
<AppShell height="fill" topNav={<div>Nav</div>} data-testid="shell">
<div>Content</div>
</AppShell>,
);
// Only the header offset needs measuring for sticky positioning, which
// fill mode does not use. (Main is measured for keyboard access.)
const observed = new Set<unknown>();
for (const call of observeSpy.mock.calls) {
observed.add(call[0]);
}
expect(observed.has(screen.getByRole('banner'))).toBe(false);
});
// ===========================================================================
// Mobile nav slot
// ===========================================================================
it('renders mobileNav slot content', () => {
render(
<AppShell
sideNav={<TestSideNav />}
mobileNav={
<MobileNav
isOpen={true}
onOpenChange={() => {}}
header="Test App"
data-testid="appshell-mobile-nav">
<div>Mobile Nav Content</div>
</MobileNav>
}>
<div>Content</div>
</AppShell>,
);
expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();
expect(screen.getByText('Mobile Nav Content')).toBeInTheDocument();
});
it('does not render mobileNav when not provided', () => {
render(
<AppShell sideNav={<TestSideNav />}>
<div>Content</div>
</AppShell>,
);
expect(screen.queryByTestId('appshell-mobile-nav')).not.toBeInTheDocument();
});
it('uses explicit mobileNav instead of default when provided', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
render(
<AppShell
sideNav={<TestSideNav />}
mobileNav={
<MobileNav
isOpen={false}
onOpenChange={() => {}}
data-testid="appshell-mobile-nav">
<div>Mobile Nav</div>
</MobileNav>
}>
<div>Content</div>
</AppShell>,
);
// Default auto-generated mobile nav should NOT appear — only the explicit one
// (The explicit mobileNav is rendered as a ReactNode, so only one dialog exists)
const dialogs = screen.getAllByRole('dialog', {hidden: true});
expect(dialogs).toHaveLength(1);
// Explicit mobileNav slot should be rendered
expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();
});
it('mobileNav onOpenChange is called when close button is clicked', () => {
const onClose = vi.fn();
render(
<AppShell
sideNav={<TestSideNav />}
mobileNav={
<MobileNav isOpen={true} onOpenChange={onClose} header="Nav">
<div>Mobile Nav</div>
</MobileNav>
}>
<div>Content</div>
</AppShell>,
);
const closeButton = screen.getByRole('button', {
name: /close/i,
});
fireEvent.click(closeButton);
expect(onClose).toHaveBeenCalled();
});
// ===========================================================================
// Content padding
// ===========================================================================
it('passes contentPadding to main content area', () => {
render(
<AppShell contentPadding={4} data-testid="shell">
<div>Content</div>
</AppShell>,
);
// Main content should render — contentPadding is passed through
expect(screen.getByRole('main')).toBeInTheDocument();
expect(screen.getByText('Content')).toBeInTheDocument();
});
it('defaults to contentPadding={0} when not specified', () => {
render(
<AppShell data-testid="shell">
<div>Content</div>
</AppShell>,
);
// Should render without error — padding=0 is the default
expect(screen.getByRole('main')).toBeInTheDocument();
});
it('supports contentPadding={0} for full-bleed content', () => {
render(
<AppShell contentPadding={0} data-testid="shell">
<div>Full bleed content</div>
</AppShell>,
);
expect(screen.getByText('Full bleed content')).toBeInTheDocument();
});
// ===========================================================================
// Ref forwarding
// ===========================================================================
it('forwards ref to root element', () => {
const ref = vi.fn();
render(
<AppShell ref={ref} data-testid="shell">
<div>Content</div>
</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);
});
});
describe('AppShell main keyboard access', () => {
let frames: FrameRequestCallback[];
beforeEach(() => {
frames = [];
vi.stubGlobal(
'requestAnimationFrame',
vi.fn((callback: FrameRequestCallback) => {
frames.push(callback);
return frames.length;
}),
);
vi.stubGlobal('cancelAnimationFrame', vi.fn());
// jsdom does not expand LayoutContent's `overflow` into its longhands.
const nativeGetComputedStyle = window.getComputedStyle.bind(window);
vi.spyOn(window, 'getComputedStyle').mockImplementation(
(element, pseudo) => {
const computed = nativeGetComputedStyle(element, pseudo);
return new Proxy(computed, {
// eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy traps must remain synchronous
get(target, property) {
if (property === 'overflowX' || property === 'overflowY') {
return target.overflow || 'visible';
}
return Reflect.get(target, property, target);
},
});
},
);
});
afterEach(() => {
vi.unstubAllGlobals();
vi.stubGlobal('ResizeObserver', MockResizeObserver);
});
function setMainGeometry(main: HTMLElement, scrollHeight: number) {
for (const [key, value] of [
['clientWidth', 800],
['scrollWidth', 800],
['clientHeight', 300],
['scrollHeight', scrollHeight],
['scrollTop', 0],
['scrollLeft', 0],
] as const) {
Object.defineProperty(main, key, {
configurable: true,
value,
writable: true,
});
}
}
function remeasure() {
act(() => {
window.dispatchEvent(new Event('resize'));
});
act(() => {
const pending = frames.splice(0);
pending.forEach(callback => callback(performance.now()));
});
}
it('makes main a keyboard stop while it scrolls overflowing content, and a skip target again once it fits', () => {
render(
<AppShell topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
const main = screen.getByRole('main');
expect(main).toHaveAttribute('tabindex', '-1');
setMainGeometry(main, 1200);
remeasure();
expect(main).toHaveAttribute('tabindex', '0');
setMainGeometry(main, 300);
remeasure();
expect(main).toHaveAttribute('tabindex', '-1');
});
// Main's ref owns both: React detaches it on unmount, and the detach
// releases the overflow observation and the keyboard delegation. Each
// listener is matched by its exact handler, so another owner's cleanup
// (the focus-ring Effect listens for the same event types) cannot stand in.
it('releases the overflow observation and the keyboard delegation on unmount', () => {
const windowAdd = vi.spyOn(window, 'addEventListener');
const {unmount} = render(
<AppShell topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
const overflowListeners = windowAdd.mock.calls.filter(
([type]) => type === 'resize',
);
expect(overflowListeners.length).toBeGreaterThan(0);
const main = screen.getByRole('main');
const documentAdd = vi.spyOn(document, 'addEventListener');
setMainGeometry(main, 1200);
remeasure();
// Main became a scroll region, so the delegation attached its listeners.
expect(main).toHaveAttribute('tabindex', '0');
const delegationListeners = [...documentAdd.mock.calls];
expect(delegationListeners.map(([type]) => type)).toEqual(
expect.arrayContaining(['keydown', 'keyup', 'pointerdown', 'focusin']),
);
const documentRemove = vi.spyOn(document, 'removeEventListener');
const windowRemove = vi.spyOn(window, 'removeEventListener');
unmount();
for (const [type, listener, options] of delegationListeners) {
expect(documentRemove).toHaveBeenCalledWith(type, listener, options);
}
for (const [type, listener] of overflowListeners) {
expect(windowRemove).toHaveBeenCalledWith(type, listener);
}
});
it('observes main only with fill, where it can become a keyboard stop', () => {
const observed: Element[] = [];
vi.stubGlobal(
'ResizeObserver',
class {
constructor(public callback: ResizeObserverCallback) {}
observe(target: Element) {
observed.push(target);
}
unobserve() {}
disconnect() {}
},
);
const inMain = (main: HTMLElement) =>
observed.filter(target => target === main || main.contains(target));
const {unmount} = render(
<AppShell height="auto" topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
expect(inMain(screen.getByRole('main'))).toEqual([]);
unmount();
render(
<AppShell topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
expect(inMain(screen.getByRole('main')).length).toBeGreaterThan(0);
});
it('stops observing main when the shell switches to auto, and measures it again back in fill', () => {
const {rerender} = render(
<AppShell topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
const main = screen.getByRole('main');
setMainGeometry(main, 1200);
remeasure();
expect(main).toHaveAttribute('tabindex', '0');
rerender(
<AppShell height="auto" topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
expect(screen.getByRole('main')).toHaveAttribute('tabindex', '-1');
remeasure();
expect(screen.getByRole('main')).toHaveAttribute('tabindex', '-1');
// Back in fill, main is measured as it attaches, with no other signal.
rerender(
<AppShell topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
expect(screen.getByRole('main')).toHaveAttribute('tabindex', '0');
});
it('never makes main a keyboard stop when the page scrolls instead (auto)', () => {
render(
<AppShell height="auto" topNav={<div>Nav</div>}>
<p>Long content</p>
</AppShell>,
);
const main = screen.getByRole('main');
setMainGeometry(main, 1200);
remeasure();
expect(main).toHaveAttribute('tabindex', '-1');
});
});
describe('AppShell layout root (FR18)', () => {
// A custom property set to `initial` reads back as `initial`; an empty
// value would mean the root declares nothing.
const CLEARED_READBACK = ['initial'];
function shell(testId: string) {
return (
<AppShell
data-testid={testId}
contentPadding={6}
topNav={
<TopNav label="Main" heading={<TopNavHeading heading="App" />} />
}
sideNav={
<SideNav>
<SideNavSection title="Main" isHeaderHidden>
<SideNavItem label="Dashboard" href="#" isSelected />
</SideNavSection>
</SideNav>
}>
{/* A page Layout of the app's own: its header takes the divider
default of the nearest Layout that sets one. */}
<Layout
header={<LayoutHeader>Page header</LayoutHeader>}
content={<p>Page content</p>}
/>
</AppShell>
);
}
/** The shell's markup without its generated ids, for comparing two renders. */
function markup(testId: string): string {
const root = screen.getByTestId(testId);
return root.outerHTML
.replaceAll(testId, 'shell')
.replace(/(id|for|aria-[a-z]+|href)="[^"]*"/g, '$1=""');
}
it('stops the container padding, Layout values and height cap of a padded host at its root', () => {
render(<Card padding={3}>{shell('shell')}</Card>);
const computed = getComputedStyle(screen.getByTestId('shell'));
for (const edge of [
'inline-start',
'inline-end',
'block-start',
'block-end',
]) {
expect(
computed.getPropertyValue(`--container-padding-${edge}`),
edge,
).toBe('0px');
}
for (const name of [
'--layout-padding-outer-x',
'--layout-padding-outer-y',
'--layout-padding-own-outer-x',
'--layout-padding-own-outer-y',
'--layout-padding-inner-x',
'--layout-padding-inner-y',
'--layout-content-width',
'--layout-alignment-width',
'--_layout-flush-block-start',
'--_layout-flush-block-end',
'--_section-padding-propagated',
'--container-max-height',
]) {
expect(CLEARED_READBACK, name).toContain(computed.getPropertyValue(name));
}
});
it('renders the same shell inside a padded Card and inside a Layout as at the page root', () => {
const {unmount} = render(shell('shell'));
const atRoot = markup('shell');
unmount();
const inCard = render(<Card padding={3}>{shell('shell')}</Card>);
expect(markup('shell')).toBe(atRoot);
inCard.unmount();
render(
<Layout
padding={4}
defaultHasDividers
header={<LayoutHeader>Outer header</LayoutHeader>}
content={shell('shell')}
/>,
);
expect(markup('shell')).toBe(atRoot);
});
it('stops an enclosing divider default for every child of the root, the mobile nav node too', () => {
render(
<Layout
defaultHasDividers
content={
<AppShell
data-testid="shell"
mobileNav={
<LayoutHeader data-testid="mobile-header">Menu</LayoutHeader>
}>
<p>Page content</p>
</AppShell>
}
/>,
);
expect(screen.getByTestId('mobile-header')).not.toHaveAttribute(
'data-divider',
);
});
it('resets the Layout area and slot contexts for every child of the root', () => {
let seen: unknown = 'unrendered';
function Probe() {
seen = {area: use(LayoutAreaContext), slots: use(LayoutSlotsContext)};
return null;
}
render(
<Layout
header={<p>Outer header</p>}
start={<p>Outer start</p>}
content={
<AppShell mobileNav={<Probe />}>
<p>Page content</p>
</AppShell>
}
/>,
);
// Inside the outer Layout's content area the probe would read area
// 'content' and the outer header and start slots; at the shell's root
// both are back to their defaults.
expect(seen).toEqual({area: null, slots: DEFAULT_LAYOUT_SLOTS});
});
it('keeps the caller style and a Section host out of each other', () => {
render(
<Section padding={6}>
<AppShell
data-testid="shell"
style={{['--container-padding-inline-start' as string]: '8px'}}>
<p>Page content</p>
</AppShell>
</Section>,
);
const computed = getComputedStyle(screen.getByTestId('shell'));
// The Section's propagated padding stops at the root...
expect(CLEARED_READBACK).toContain(
computed.getPropertyValue('--_section-padding-propagated'),
);
// ...and the caller's own style still applies after the reset (FR15).
expect(computed.getPropertyValue('--container-padding-inline-start')).toBe(
'8px',
);
});
});