Skip to content

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

TypeScript

fix(docsite): an opened blog heading link lands below the whole sticky header (#9856)

Cindy Zhanga76c68a139bd
diff --git a/apps/docsite/e2e/blog-heading-links.spec.ts b/apps/docsite/e2e/blog-heading-links.spec.ts
index 0e79ad0a91..13b7ee36a4 100644
--- a/apps/docsite/e2e/blog-heading-links.spec.ts
+++ b/apps/docsite/e2e/blog-heading-links.spec.ts
@@ -5,7 +5,8 @@
* @input Production docsite blog post (the 0.6.0 release post)
* @output Proof that post headings reveal a copy-link control, that it copies
* the heading's permalink, and that a copied link lands the heading below
- * the sticky header, left to right and right to left
+ * the sticky header on a fresh load and in place, left to right and right
+ * to left
* @position Docsite browser tests; jsdom has no hover, clipboard, or layout
*/
@@ -58,6 +59,26 @@ test('hovering a post heading reveals a control that copies its permalink', asyn
expect(new URL(copied).hash).toBe(`#${HEADING_ID}`);
});
+test('opening a copied heading link lands the heading below the sticky header', async ({
+ page,
+}) => {
+ await page.setViewportSize({width: 1280, height: 900});
+ // A fresh load scrolls to the fragment before hydration. The offset must
+ // already include the whole header, banner included.
+ await page.goto(`${POST}#${HEADING_ID}`);
+
+ const heading = page.getByRole('heading', {name: HEADING});
+ await expect(heading).toBeInViewport();
+ const headerBox = await page
+ .locator('.astryx-app-shell-header')
+ .first()
+ .boundingBox();
+ const headingTop = (await heading.boundingBox())?.y ?? -1;
+ expect(headingTop).toBeGreaterThanOrEqual(
+ (headerBox?.y ?? 0) + (headerBox?.height ?? 0) - 1,
+ );
+});
+
for (const [dir, colorScheme] of [
['ltr', 'light'],
['rtl', 'dark'],
diff --git a/apps/docsite/src/app/blog/layout.tsx b/apps/docsite/src/app/blog/layout.tsx
index f2d7c8c08e..463da09ef7 100644
--- a/apps/docsite/src/app/blog/layout.tsx
+++ b/apps/docsite/src/app/blog/layout.tsx
@@ -8,6 +8,7 @@
import {AppShell} from '@astryxdesign/core/AppShell';
import {SharedTopNav} from '../../components/SharedTopNav';
+import {HeaderHeightSeed} from '../../components/HeaderHeightSeed';
import {DocsBanner} from '../../components/InternalDocsPrompt';
import {SiteFooter} from '../../components/SiteFooter';
import {getCopyrightYear} from '../../lib/copyrightYear';
@@ -25,7 +26,12 @@ export default async function BlogLayout({
height="auto"
mobileNav={false}
banner={<DocsBanner />}
- topNav={<SharedTopNav />}>
+ topNav={
+ <>
+ <SharedTopNav />
+ <HeaderHeightSeed />
+ </>
+ }>
{children}
<SiteFooter year={year} />
</AppShell>
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index 7cf6bd452a..aaa14f21da 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -6,7 +6,7 @@
* @file DocsShell.tsx
* @input Route metadata, component registry, and the rendered AppShell header
* @output Docs navigation with a stable sidebar offset before hydration
- * @position Docsite-only shell and first-paint header measurement
+ * @position Docsite-only shell
*/
import {useState, useMemo} from 'react';
@@ -18,6 +18,7 @@ import {SideNav, SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
import {TextInput} from '@astryxdesign/core/TextInput';
import {Icon} from '@astryxdesign/core/Icon';
import {SharedTopNav} from './SharedTopNav';
+import {HeaderHeightSeed} from './HeaderHeightSeed';
import {DocsBanner} from './InternalDocsPrompt';
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
@@ -62,24 +63,6 @@ const foundationsSort = (a: DocTopic, b: DocTopic) => {
return a.title.localeCompare(b.title);
};
-// Seed the full header height while parsing, before restored scroll can put
-// the sidebar under it, and refresh once its fonts settle. CSSOM leaves React's
-// DOM unchanged; the existing observer's inline value takes over after hydration.
-const initialHeaderHeightScript = `(() => {
- const script = document.currentScript;
- const header = script?.closest('.astryx-app-shell-header');
- const style = script?.previousElementSibling;
- const sheet = style?.sheet;
- const publish = () => {
- if (!header?.isConnected || !style?.isConnected || !sheet) return;
- if (sheet.cssRules.length === 0) sheet.insertRule(':root {}');
- sheet.cssRules[0].style.setProperty('--appshell-header-height',
- header.getBoundingClientRect().height + 'px');
- };
- publish();
- document.fonts.ready.then(publish);
-})();`;
-
// ── Shell ──────────────────────────────────────────────────────────────
export function DocsShell({children, packages, docTopics}: DocsShellProps) {
@@ -188,12 +171,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {
topNav={
<>
<SharedTopNav />
- {/* Parser-blocking measurement precedes all sidebar markup, including
- when the response is streamed. Stylesheets above it are loaded. */}
- <style />
- <script
- dangerouslySetInnerHTML={{__html: initialHeaderHeightScript}}
- />
+ <HeaderHeightSeed />
</>
}
sideNav={
diff --git a/apps/docsite/src/components/HeaderHeightSeed.tsx b/apps/docsite/src/components/HeaderHeightSeed.tsx
new file mode 100644
index 0000000000..adbcbb4b6d
--- /dev/null
+++ b/apps/docsite/src/components/HeaderHeightSeed.tsx
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file HeaderHeightSeed.tsx
+ * @input The AppShell header that contains it, banner included
+ * @output --appshell-header-height set to that header's height while the page
+ * parses, before the first paint
+ * @position Docsite shells; render it in AppShell's topNav slot, after the nav
+ */
+
+// The browser can scroll before hydration: to a restored position, or to the
+// fragment of an opened link. Each offset that reads the variable must then
+// already include the banner. The script measures again when the fonts are
+// ready. CSSOM leaves React's DOM unchanged. After hydration, the header
+// observer's inline value takes over.
+const seedScript = `(() => {
+ const script = document.currentScript;
+ const header = script?.closest('.astryx-app-shell-header');
+ const style = script?.previousElementSibling;
+ const sheet = style?.sheet;
+ const publish = () => {
+ if (!header?.isConnected || !style?.isConnected || !sheet) return;
+ if (sheet.cssRules.length === 0) sheet.insertRule(':root {}');
+ sheet.cssRules[0].style.setProperty('--appshell-header-height',
+ header.getBoundingClientRect().height + 'px');
+ };
+ publish();
+ document.fonts.ready.then(publish);
+})();`;
+
+export function HeaderHeightSeed() {
+ return (
+ <>
+ {/* Parser-blocking measurement precedes the page content, including
+ when the response is streamed. Stylesheets above it are loaded. */}
+ <style />
+ <script dangerouslySetInnerHTML={{__html: seedScript}} />
+ </>
+ );
+}