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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.cssindex 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 darkmode 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 herodiff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsxindex 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={<TopNavHeadingdiff --git a/apps/docsite/src/lib/useAppShellHeaderHeight.ts b/apps/docsite/src/lib/useAppShellHeaderHeight.tsnew file mode 100644index 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.pngnew file mode 100644index 0000000000..64be88b04dBinary files /dev/null and b/docs/pr-assets/6856/docs-1440-scrolled-after.png differdiff --git a/docs/pr-assets/6856/docs-1440-scrolled-before.png b/docs/pr-assets/6856/docs-1440-scrolled-before.pngnew file mode 100644index 0000000000..6c5ecf50caBinary files /dev/null and b/docs/pr-assets/6856/docs-1440-scrolled-before.png differdiff --git a/docs/pr-assets/6856/home-1440-banner-after.png b/docs/pr-assets/6856/home-1440-banner-after.pngnew file mode 100644index 0000000000..8245685361Binary files /dev/null and b/docs/pr-assets/6856/home-1440-banner-after.png differdiff --git a/docs/pr-assets/6856/home-1440-banner-before.png b/docs/pr-assets/6856/home-1440-banner-before.pngnew file mode 100644index 0000000000..b295ad2d84Binary files /dev/null and b/docs/pr-assets/6856/home-1440-banner-before.png differdiff --git a/docs/pr-assets/6856/home-390-banner-after.png b/docs/pr-assets/6856/home-390-banner-after.pngnew file mode 100644index 0000000000..7ab44bf1e1Binary files /dev/null and b/docs/pr-assets/6856/home-390-banner-after.png differdiff --git a/docs/pr-assets/6856/home-390-banner-before.png b/docs/pr-assets/6856/home-390-banner-before.pngnew file mode 100644index 0000000000..f48c79f7ebBinary files /dev/null and b/docs/pr-assets/6856/home-390-banner-before.png differ