Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): show mobile navigation before hydration (#6786)

Xinzi Zhou7ec7be07fd53
diff --git a/apps/docsite/e2e/mobile-navigation.spec.ts b/apps/docsite/e2e/mobile-navigation.spec.ts
new file mode 100644
index 0000000000..7cd585c5ef
--- /dev/null
+++ b/apps/docsite/e2e/mobile-navigation.spec.ts
@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file mobile-navigation.spec.ts
+ * @input Production docsite HTML/CSS, with hydration held then released
+ * @output Regression proof for initial navigation and its hydration handoff
+ * @position Docsite browser tests; jsdom cannot measure the rendered icon
+ */
+
+import {expect, test} from '@playwright/test';
+
+test('the mobile hamburger survives hydration without changing icon size or drawer ownership', async ({
+ page,
+}) => {
+ await page.setViewportSize({width: 390, height: 844});
+ let resumeHydration = () => {};
+ const hydration = new Promise<void>(resolve => {
+ resumeHydration = resolve;
+ });
+ await page.route('**/_next/**/*.js*', async route => {
+ await hydration;
+ await route.continue();
+ });
+
+ try {
+ await page.goto('/components', {waitUntil: 'commit'});
+ // First paint waits for the real render-blocking CSS, not for hydration.
+ await page.waitForFunction(
+ () => performance.getEntriesByName('first-contentful-paint').length > 0,
+ );
+ const nav = page.getByRole('navigation', {name: 'Astryx navigation'});
+ const toggle = nav.getByRole('button', {name: 'Open navigation'});
+ await expect(toggle).toHaveCount(1);
+ await expect(toggle.locator('svg')).toBeVisible();
+ const initialSize = await toggle.locator('svg').evaluate(svg => {
+ const {width, height} = svg.getBoundingClientRect();
+ return {width, height};
+ });
+
+ resumeHydration();
+ // Wait for AppShell's automatic toggle on this same document.
+ await expect(nav.getByTestId('mobile-nav-toggle')).toBeVisible();
+ await expect(toggle).toHaveCount(1);
+ await expect(toggle.locator('svg')).toBeVisible();
+ const hydratedSize = await toggle.locator('svg').evaluate(svg => {
+ const {width, height} = svg.getBoundingClientRect();
+ return {width, height};
+ });
+ expect(initialSize).toEqual(hydratedSize);
+
+ await toggle.click();
+ const drawer = page.getByRole('dialog');
+ await expect(drawer).toHaveCount(1);
+ await expect(
+ drawer.getByRole('link', {name: 'Docs', exact: true}),
+ ).toBeVisible();
+ await expect(
+ drawer.getByRole('textbox', {name: 'Search components'}),
+ ).toBeVisible();
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ await page.keyboard.press('Escape');
+ await expect(drawer).toBeHidden();
+ await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+ await expect(toggle).toBeFocused();
+ } finally {
+ resumeHydration();
+ }
+});
+
+test('desktop navigation remains available at exactly 768px before hydration', async ({
+ page,
+}) => {
+ await page.setViewportSize({width: 768, height: 844});
+ await page.route('**/_next/**/*.js*', route => route.abort());
+ await page.goto('/components', {waitUntil: 'load'});
+
+ const nav = page.getByRole('navigation', {name: 'Astryx navigation'});
+ await expect(nav.getByRole('button', {name: 'Open navigation'})).toBeHidden();
+ await expect(
+ nav.getByRole('link', {name: 'Components', exact: true}),
+ ).toBeVisible();
+ await expect(
+ page.getByRole('textbox', {name: 'Search components'}),
+ ).toBeVisible();
+});
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.css
index b3565510b6..a6cdfedb67 100644
--- a/apps/docsite/src/app/globals.css
+++ b/apps/docsite/src/app/globals.css
@@ -91,8 +91,9 @@ body:has([data-home-page]) #astryx-app-shell-main {
server-side (desktop HTML), so below the mobile breakpoint we hide it with
pure CSS — it never paints on a phone, no JS flip. The :where(:not(...))
guard scopes this to the OUTERMOST AppShell so sidenavs inside nested
- AppShell examples/previews keep their own responsive behavior. */
-@media (max-width: 768px) {
+ AppShell examples/previews keep their own responsive behavior. Match
+ AppShell's default md breakpoint: equality belongs to the desktop layout. */
+@media (width < 768px) {
.astryx-app-shell-sidenav:where(:not(.astryx-app-shell .astryx-app-shell *)) {
display: none;
}
diff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsx
index 5fdf743885..de719cd4dd 100644
--- a/apps/docsite/src/components/SharedTopNav.tsx
+++ b/apps/docsite/src/components/SharedTopNav.tsx
@@ -15,6 +15,7 @@ import {
import {useAppShellMobile} from '@astryxdesign/core/AppShell';
import {MobileNav} from '@astryxdesign/core/MobileNav';
import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
import {HStack} from '@astryxdesign/core/Layout';
import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
import {Search, HeartHandshake, Sun, Moon, Menu} from 'lucide-react';
@@ -44,10 +45,11 @@ const GitHubIcon = ({
</svg>
);
-// Responsive helpers. The desktop links and the mobile hamburger both live in
-// the DOM at all times; a pure CSS @media query decides which is visible so the
-// server-rendered HTML is correct on first paint (no post-hydration flip).
-const MOBILE_BREAKPOINT = '@media (max-width: 768px)';
+// Responsive helpers. Keep a CSS-controlled hamburger in the server HTML;
+// when AppShell switches to mobile-bar mode, its automatic toggle takes over.
+// Match AppShell's default md breakpoint: equality belongs to desktop.
+// Negate min-width so StyleX does not lower '<' to a rounded 767.99px bound.
+const MOBILE_BREAKPOINT = '@media not (min-width: 768px)';
const styles = stylex.create({
desktopNav: {
@@ -109,9 +111,15 @@ export function SharedTopNav() {
const [isMenuOpen, setIsMenuOpen] = useState(false);
const pathname = usePathname();
const {mode, themeMode, toggleMode} = useThemeMode();
- // When AppShell owns the mobile drawer (docs, which has a sideNav) we defer
- // to its single hamburger; otherwise we render our own.
- const {isMobileNavEnabled, closeMobileNav} = useAppShellMobile();
+ // Enabled describes drawer ownership, not whether its automatic hamburger
+ // has rendered yet. During SSR AppShell still renders the desktop top bar.
+ const {
+ isMobileNavEnabled,
+ isMobileNavOpen,
+ mobileNavId,
+ openMobileNav,
+ closeMobileNav,
+ } = useAppShellMobile();
const renderMode = useTopNavRenderMode();
useEffect(() => {
@@ -278,15 +286,30 @@ export function SharedTopNav() {
trackClickCta({page: 'landing', target: 'get_started'})
}
/>
- {!isMobileNavEnabled && (
+ {(!isMobileNavEnabled || renderMode === 'default') && (
<div {...stylex.props(styles.mobileToggle)}>
<Button
- label="Open menu"
+ label={isMobileNavEnabled ? 'Open navigation' : 'Open menu'}
tooltip="Menu"
variant="ghost"
isIconOnly
- icon={<Menu size={20} />}
- onClick={() => setIsMenuOpen(true)}
+ icon={
+ isMobileNavEnabled ? (
+ // Match AppShell's glyph and Button-owned icon size.
+ <Icon icon="menu" color="inherit" />
+ ) : (
+ <Menu size={20} />
+ )
+ }
+ aria-expanded={
+ isMobileNavEnabled ? isMobileNavOpen : undefined
+ }
+ aria-controls={isMobileNavEnabled ? mobileNavId : undefined}
+ onClick={
+ isMobileNavEnabled
+ ? openMobileNav
+ : () => setIsMenuOpen(true)
+ }
/>
</div>
)}