Skip to content

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

TypeScript

fix(docsite): measure the whole AppShell header for --appshell-header-height (#6856)

Kenton Quatman737ec59c2909
diff --git a/apps/docsite/e2e/header-offset.spec.ts b/apps/docsite/e2e/header-offset.spec.ts
new file mode 100644
index 0000000000..42cec06db4
--- /dev/null
+++ b/apps/docsite/e2e/header-offset.spec.ts
@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file header-offset.spec.ts
+ * @input Production docsite home page with the canary banner in the header
+ * @output Regression proof that --appshell-header-height covers the whole
+ * AppShell header, so the hero and its nav backdrop clear the banner
+ * @position Docsite browser tests; jsdom cannot lay out the header
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+
+function readHeaderHeightVar(page: Page) {
+ return page.evaluate(() =>
+ Math.round(
+ parseFloat(
+ getComputedStyle(document.documentElement).getPropertyValue(
+ '--appshell-header-height',
+ ),
+ ),
+ ),
+ );
+}
+
+test('the canary banner does not leave the hero and nav backdrop behind it', async ({
+ page,
+}) => {
+ await page.setViewportSize({width: 1440, height: 900});
+ await page.goto('/');
+
+ const banner = page
+ .getByRole('alert')
+ .filter({hasText: "You're viewing unreleased docs"});
+ test.skip((await banner.count()) === 0, 'Only canary builds show the banner');
+
+ const header = page.locator('.astryx-app-shell-header').first();
+ const nav = page.getByRole('navigation', {name: 'Astryx navigation'});
+ const heightOf = async (locator: typeof header) =>
+ Math.round((await locator.boundingBox())?.height ?? Number.NaN);
+
+ const navHeight = await heightOf(nav);
+ const headerHeight = await heightOf(header);
+ expect(headerHeight).toBeGreaterThan(navHeight);
+ await expect.poll(() => readHeaderHeightVar(page)).toBe(headerHeight);
+
+ // The pinned hero band starts below the whole header, not one nav height
+ // down, under the banner.
+ const heroTop = await page
+ .locator('[data-home-page="true"]')
+ .first()
+ .evaluate(element => Math.round(element.getBoundingClientRect().top));
+ expect(heroTop).toBe(headerHeight);
+
+ await banner.getByRole('button', {name: /^Dismiss/}).click();
+ await expect(banner).toHaveCount(0);
+ await expect.poll(() => heightOf(header)).toBe(navHeight);
+ await expect.poll(() => readHeaderHeightVar(page)).toBe(navHeight);
+});
diff --git a/apps/docsite/src/__tests__/app-shell-header-height.test.tsx b/apps/docsite/src/__tests__/app-shell-header-height.test.tsx
new file mode 100644
index 0000000000..dd2043a430
--- /dev/null
+++ b/apps/docsite/src/__tests__/app-shell-header-height.test.tsx
@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// @vitest-environment jsdom
+
+import {useRef} from 'react';
+import {act, render} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {useAppShellHeaderHeight} from '../lib/useAppShellHeaderHeight';
+
+const HEADER_HEIGHT_VAR = '--appshell-header-height';
+
+let headerHeight = 0;
+let notifyResize: (() => void) | null = null;
+const disconnectSpy = vi.fn();
+
+function Nav() {
+ const ref = useRef<HTMLElement>(null);
+ useAppShellHeaderHeight(ref);
+ return <nav ref={ref} />;
+}
+
+function readHeaderHeightVar() {
+ return document.documentElement.style.getPropertyValue(HEADER_HEIGHT_VAR);
+}
+
+beforeEach(() => {
+ headerHeight = 0;
+ notifyResize = null;
+ disconnectSpy.mockClear();
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class {
+ constructor(callback: ResizeObserverCallback) {
+ notifyResize = () => callback([], this as unknown as ResizeObserver);
+ }
+ observe() {}
+ unobserve() {}
+ disconnect() {
+ disconnectSpy();
+ }
+ },
+ );
+ // Only the AppShell header has a size, so measuring the nav instead of the
+ // header it sits in would read 0.
+ vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(
+ function (this: Element) {
+ const height = this.classList.contains('astryx-app-shell-header')
+ ? headerHeight
+ : 0;
+ return {height} as DOMRect;
+ },
+ );
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ document.documentElement.style.removeProperty(HEADER_HEIGHT_VAR);
+});
+
+describe('useAppShellHeaderHeight', () => {
+ it('publishes the whole header height, banner included, and follows resizes', () => {
+ // Canary banner (84px) above the nav (48px).
+ headerHeight = 132;
+ render(
+ <div className="astryx-app-shell-header">
+ <div role="alert">Canary</div>
+ <Nav />
+ </div>,
+ );
+ expect(readHeaderHeightVar()).toBe('132px');
+
+ // Dismissing the banner leaves the nav alone.
+ headerHeight = 48;
+ act(() => notifyResize?.());
+ expect(readHeaderHeightVar()).toBe('48px');
+ });
+
+ it('restores the stylesheet seed and stops observing on unmount', () => {
+ headerHeight = 132;
+ const {unmount} = render(
+ <div className="astryx-app-shell-header">
+ <Nav />
+ </div>,
+ );
+ unmount();
+ expect(readHeaderHeightVar()).toBe('');
+ expect(disconnectSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it('ignores a nav rendered outside the header, like the mobile drawer copy', () => {
+ headerHeight = 132;
+ render(<Nav />);
+ expect(readHeaderHeightVar()).toBe('');
+ expect(notifyResize).toBeNull();
+ });
+});
diff --git a/apps/docsite/src/app/(site)/page.tsx b/apps/docsite/src/app/(site)/page.tsx
index 3368ecb1a0..ddb18babe3 100644
--- a/apps/docsite/src/app/(site)/page.tsx
+++ b/apps/docsite/src/app/(site)/page.tsx
@@ -67,12 +67,12 @@ const styles = stylex.create({
default: 'flex-start',
'@media (min-width: 1024px)': 'center',
},
- // Narrow: in flow under the transparent nav, so pad by nav height to clear
- // it. Desktop is fixed + centered, so none.
+ // Narrow: in flow below the header. Pad by the nav's height plus the gap;
+ // --spacing-12 rather than --appshell-header-height, which also counts the
+ // canary banner. Desktop is fixed + centered, so none.
paddingBlockStart: {
- default: 'calc(var(--appshell-header-height, 0px) + var(--spacing-8))',
- '@media (min-width: 768px)':
- 'calc(var(--appshell-header-height, 0px) + var(--hero-gap))',
+ default: 'calc(var(--spacing-12) + var(--spacing-8))',
+ '@media (min-width: 768px)': 'calc(var(--spacing-12) + var(--hero-gap))',
'@media (min-width: 1024px)': 0,
},
paddingBlockEnd: spacingVars['--spacing-12'],
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.css
index a6cdfedb67..1ee2340d02 100644
--- a/apps/docsite/src/app/globals.css
+++ b/apps/docsite/src/app/globals.css
@@ -34,13 +34,14 @@
override real Astryx semantic tokens). Each is a light-dark() pair so dark
mode is handled by the value itself, no consumer logic required. */
:root {
- /* AppShell measures its header post-hydration and sets
- --appshell-header-height on the shell element. Until that runs, every
- consumer (the hero's fixed `top`, the nav backdrop, the docs content
- padding) falls back to mismatched literals, so the top spacing visibly
- pops in on load (#2713). Seed the auto-mode header height (--spacing-12 =
- 48px) here so the very first paint already reserves the right offset; the
- AppShell then overwrites it with the measured value (identical, no jump). */
+ /* SharedTopNav measures the AppShell header (banner included) after
+ hydration and sets --appshell-header-height on the root element. Until
+ that runs, every consumer (the hero's fixed `top`, the nav backdrop, the
+ docs table of contents) falls back to mismatched literals, so the top
+ spacing visibly pops in on load (#2713). Seed the auto-mode header height
+ (--spacing-12 = 48px) here so the very first paint already reserves the
+ right offset; the measured value then overwrites it (identical, no jump,
+ unless a banner is showing). */
--appshell-header-height: var(--spacing-12, 48px);
/* Feature card backdrop. Soft pastel blue in light mode, deep navy in
@@ -71,11 +72,15 @@
element so the first paint already has the offset in place.
The --appshell-header-height variable is seeded at :root (above) and then
- re-set by the AppShell once it measures the rendered header. The literal
- fallbacks below only apply if the :root seed is ever missing. */
+ re-set by SharedTopNav once it measures the rendered header. The literal
+ fallback below only applies if the :root seed is ever missing.
+
+ The padding is the nav's own height (--spacing-12 = 48px) rather than the
+ measured header height, so the canary banner, which also lives in the
+ header, does not push every page's content down by its own height. */
body:not(:has([data-playground-page])) #astryx-app-shell-main {
scroll-padding-top: var(--appshell-header-height, 64px);
- padding-top: var(--appshell-header-height, 64px);
+ padding-top: var(--spacing-12, 48px);
}
/* The home page is excluded from the padding rule above — its sticky hero
diff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsx
index de719cd4dd..ce7333b484 100644
--- a/apps/docsite/src/components/SharedTopNav.tsx
+++ b/apps/docsite/src/components/SharedTopNav.tsx
@@ -2,7 +2,7 @@
'use client';
-import {lazy, Suspense, useEffect, useState} from 'react';
+import {lazy, Suspense, useEffect, useRef, useState} from 'react';
import {usePathname} from 'next/navigation';
import * as stylex from '@stylexjs/stylex';
import {
@@ -23,6 +23,7 @@ import {GITHUB_REPO} from '../constants';
import {AstryxIcon} from './logos';
import {useThemeMode} from '../app/providers';
import {trackSearch, trackClickCta} from '../lib/analytics';
+import {useAppShellHeaderHeight} from '../lib/useAppShellHeaderHeight';
const LazySearchPalette = lazy(() =>
import('./SearchPalette').then(module => ({default: module.SearchPalette})),
@@ -121,6 +122,8 @@ export function SharedTopNav() {
closeMobileNav,
} = useAppShellMobile();
const renderMode = useTopNavRenderMode();
+ const navRef = useRef<HTMLElement>(null);
+ useAppShellHeaderHeight(navRef);
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
@@ -182,6 +185,7 @@ export function SharedTopNav() {
return (
<>
<TopNav
+ ref={navRef}
label="Astryx navigation"
heading={
<TopNavHeading
diff --git a/apps/docsite/src/lib/useAppShellHeaderHeight.ts b/apps/docsite/src/lib/useAppShellHeaderHeight.ts
new file mode 100644
index 0000000000..95515bde18
--- /dev/null
+++ b/apps/docsite/src/lib/useAppShellHeaderHeight.ts
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLayoutEffect, type RefObject} from 'react';
+
+/**
+ * Publishes the rendered height of the AppShell header that contains `ref` as
+ * `--appshell-header-height` on the root element, and keeps it current as the
+ * header resizes (for example when the canary banner is dismissed).
+ *
+ * The docsite positions page chrome against that variable: the home hero's nav
+ * backdrop and pinned layers, and the docs table of contents. AppShell only
+ * measures its header into a private custom property, so the docsite measures
+ * the whole header itself, banner included. Unmounting restores the `:root`
+ * seed in globals.css.
+ */
+export function useAppShellHeaderHeight(
+ ref: RefObject<HTMLElement | null>,
+): void {
+ useLayoutEffect(() => {
+ // A nav rendered into AppShell's mobile drawer sits outside the header,
+ // so there is nothing to measure.
+ const header = ref.current?.closest('.astryx-app-shell-header');
+ if (header == null) {
+ return;
+ }
+ const root = document.documentElement;
+ const publish = () => {
+ root.style.setProperty(
+ '--appshell-header-height',
+ `${header.getBoundingClientRect().height}px`,
+ );
+ };
+ publish();
+ const observer = new ResizeObserver(publish);
+ observer.observe(header);
+ return () => {
+ observer.disconnect();
+ root.style.removeProperty('--appshell-header-height');
+ };
+ }, [ref]);
+}
diff --git a/docs/pr-assets/6856/docs-1440-scrolled-after.png b/docs/pr-assets/6856/docs-1440-scrolled-after.png
new file mode 100644
index 0000000000..64be88b04d
Binary files /dev/null and b/docs/pr-assets/6856/docs-1440-scrolled-after.png differ
diff --git a/docs/pr-assets/6856/docs-1440-scrolled-before.png b/docs/pr-assets/6856/docs-1440-scrolled-before.png
new file mode 100644
index 0000000000..6c5ecf50ca
Binary files /dev/null and b/docs/pr-assets/6856/docs-1440-scrolled-before.png differ
diff --git a/docs/pr-assets/6856/home-1440-banner-after.png b/docs/pr-assets/6856/home-1440-banner-after.png
new file mode 100644
index 0000000000..8245685361
Binary files /dev/null and b/docs/pr-assets/6856/home-1440-banner-after.png differ
diff --git a/docs/pr-assets/6856/home-1440-banner-before.png b/docs/pr-assets/6856/home-1440-banner-before.png
new file mode 100644
index 0000000000..b295ad2d84
Binary files /dev/null and b/docs/pr-assets/6856/home-1440-banner-before.png differ
diff --git a/docs/pr-assets/6856/home-390-banner-after.png b/docs/pr-assets/6856/home-390-banner-after.png
new file mode 100644
index 0000000000..7ab44bf1e1
Binary files /dev/null and b/docs/pr-assets/6856/home-390-banner-after.png differ
diff --git a/docs/pr-assets/6856/home-390-banner-before.png b/docs/pr-assets/6856/home-390-banner-before.png
new file mode 100644
index 0000000000..f48c79f7eb
Binary files /dev/null and b/docs/pr-assets/6856/home-390-banner-before.png differ