Skip to content

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

TypeScript

fix/docsite: flashing of desktop UI on docs/components (#3665)

Joseph1df7363bb3b0
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.css
index 6493d07baf..eaa6545e15 100644
--- a/apps/docsite/src/app/globals.css
+++ b/apps/docsite/src/app/globals.css
@@ -78,6 +78,17 @@ body:has([data-home-page]) #astryx-app-shell-main {
padding-top: 0;
}
+/* The docs/components sidebar is a desktop affordance. AppShell renders it
+ 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) {
+ .astryx-app-shell-sidenav:where(:not(.astryx-app-shell .astryx-app-shell *)) {
+ display: none;
+ }
+}
+
/* Translucent top nav — frosted glass effect.
The :where(:not(.astryx-app-shell .astryx-app-shell *)) guard scopes every frost
diff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsx
index 84009b23a6..6cf1d1e4f3 100644
--- a/apps/docsite/src/components/SharedTopNav.tsx
+++ b/apps/docsite/src/components/SharedTopNav.tsx
@@ -10,7 +10,9 @@ import {
TopNavHeading,
TopNavItem,
TopNavRenderContext,
+ useTopNavRenderMode,
} from '@astryxdesign/core/TopNav';
+import {useAppShellMobile} from '@astryxdesign/core/AppShell';
import {MobileNav} from '@astryxdesign/core/MobileNav';
import {Button} from '@astryxdesign/core/Button';
import {HStack} from '@astryxdesign/core/Layout';
@@ -107,6 +109,10 @@ 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();
+ const renderMode = useTopNavRenderMode();
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
@@ -153,6 +159,17 @@ export function SharedTopNav() {
return undefined;
};
+ const navLinks = (onNavigate?: () => void) =>
+ NAV_ITEMS.map(item => (
+ <TopNavItem
+ key={item.key}
+ label={item.label}
+ href={item.href}
+ isSelected={getActiveItem() === item.key}
+ onClick={onNavigate}
+ />
+ ));
+
return (
<>
<TopNav
@@ -172,16 +189,13 @@ export function SharedTopNav() {
/>
}
centerContent={
- <div {...stylex.props(styles.desktopNav)}>
- {NAV_ITEMS.map(item => (
- <TopNavItem
- key={item.key}
- label={item.label}
- href={item.href}
- isSelected={getActiveItem() === item.key}
- />
- ))}
- </div>
+ renderMode === 'drawer' ? (
+ // Bare items — AppShell's drawer supplies its own vertical list;
+ // the desktopNav wrapper would hide them (display:none) here.
+ <>{navLinks(closeMobileNav)}</>
+ ) : (
+ <div {...stylex.props(styles.desktopNav)}>{navLinks()}</div>
+ )
}
endContent={
<HStack gap={2}>
@@ -262,16 +276,18 @@ export function SharedTopNav() {
trackClickCta({page: 'landing', target: 'get_started'})
}
/>
- <div {...stylex.props(styles.mobileToggle)}>
- <Button
- label="Open menu"
- tooltip="Menu"
- variant="ghost"
- isIconOnly
- icon={<Menu size={20} />}
- onClick={() => setIsMenuOpen(true)}
- />
- </div>
+ {!isMobileNavEnabled && (
+ <div {...stylex.props(styles.mobileToggle)}>
+ <Button
+ label="Open menu"
+ tooltip="Menu"
+ variant="ghost"
+ isIconOnly
+ icon={<Menu size={20} />}
+ onClick={() => setIsMenuOpen(true)}
+ />
+ </div>
+ )}
</HStack>
}
/>
@@ -283,34 +299,28 @@ export function SharedTopNav() {
docTopics={docTopics}
templates={templates}
/>
- <MobileNav
- isOpen={isMenuOpen}
- onOpenChange={setIsMenuOpen}
- side="end"
- label="Astryx navigation"
- header={
- <AstryxIcon
- width={24}
- height={24}
- role="img"
- aria-label="Astryx"
- style={{display: 'block', color: 'var(--color-brand)'}}
- />
- }>
- <TopNavRenderContext value="drawer">
- <div {...stylex.props(styles.drawerItems)}>
- {NAV_ITEMS.map(item => (
- <TopNavItem
- key={item.key}
- label={item.label}
- href={item.href}
- isSelected={getActiveItem() === item.key}
- onClick={() => setIsMenuOpen(false)}
- />
- ))}
- </div>
- </TopNavRenderContext>
- </MobileNav>
+ {!isMobileNavEnabled && (
+ <MobileNav
+ isOpen={isMenuOpen}
+ onOpenChange={setIsMenuOpen}
+ side="end"
+ label="Astryx navigation"
+ header={
+ <AstryxIcon
+ width={24}
+ height={24}
+ role="img"
+ aria-label="Astryx"
+ style={{display: 'block', color: 'var(--color-brand)'}}
+ />
+ }>
+ <TopNavRenderContext value="drawer">
+ <div {...stylex.props(styles.drawerItems)}>
+ {navLinks(() => setIsMenuOpen(false))}
+ </div>
+ </TopNavRenderContext>
+ </MobileNav>
+ )}
</>
);
}
diff --git a/apps/docsite/src/components/docs/DocPageLayout.tsx b/apps/docsite/src/components/docs/DocPageLayout.tsx
index 755bc47916..fdc9549258 100644
--- a/apps/docsite/src/components/docs/DocPageLayout.tsx
+++ b/apps/docsite/src/components/docs/DocPageLayout.tsx
@@ -29,6 +29,13 @@ import {
} from '@astryxdesign/core/theme/tokens.stylex';
import {layout} from '../../layout.stylex';
+// Both the aside and the mobile jump-menu are styled for their side of this
+// breakpoint so the initial (server) render is jank-free; useMediaQuery then
+// mounts only the side the viewport needs, so the other's scroll-spy/observers
+// don't run.
+const TOC_BREAKPOINT = '(max-width: 1024px)';
+const TOC_MEDIA_QUERY = `@media ${TOC_BREAKPOINT}`;
+
const styles = stylex.create({
// Centered article when there is no outline aside (original behavior).
sectionCentered: {
@@ -48,9 +55,13 @@ const styles = stylex.create({
},
// Article that shares the row with a sticky outline aside. Mirrors the
// larger/airier article body typography from sectionCentered so pages with
- // an outline keep the same readable prose.
+ // an outline keep the same readable prose. Below the breakpoint the aside is
+ // hidden, so the article re-centers to fill the row.
sectionInRow: {
- marginInline: 0,
+ marginInline: {
+ default: 0,
+ [TOC_MEDIA_QUERY]: 'auto',
+ },
flexShrink: 1,
minWidth: 0,
[typeScaleVars['--text-body-size']]: '1.0625rem', // 17px
@@ -65,6 +76,11 @@ const styles = stylex.create({
width: '100%',
},
aside: {
+ // Desktop only — hidden below the breakpoint where the Selector takes over.
+ display: {
+ default: 'block',
+ [TOC_MEDIA_QUERY]: 'none',
+ },
position: 'sticky',
top: 'calc(var(--appshell-header-height, 0px) + 24px)',
alignSelf: 'flex-start',
@@ -74,8 +90,12 @@ const styles = stylex.create({
// Mobile on-this-page selector: pinned below the app header while scrolling.
// Lives directly in the article column so its sticky range spans the article;
// an opaque background + bottom border keep content readable as it scrolls
- // underneath.
+ // underneath. Shown only below the breakpoint.
mobileOutline: {
+ display: {
+ default: 'none',
+ [TOC_MEDIA_QUERY]: 'block',
+ },
position: 'sticky',
top: 'var(--appshell-header-height, 0px)',
zIndex: 1,
@@ -85,6 +105,15 @@ const styles = stylex.create({
borderBottomStyle: 'solid',
borderBottomColor: colorVars['--color-border'],
},
+ // Title divider. On outline pages the mobile Selector carries its own bottom
+ // border, so the divider is hidden below the breakpoint to avoid a doubled
+ // separator (applied only when an outline is present).
+ titleDivider: {
+ display: {
+ default: 'block',
+ [TOC_MEDIA_QUERY]: 'none',
+ },
+ },
});
export function DocPageLayout({
@@ -104,7 +133,7 @@ export function DocPageLayout({
outline?: OutlineItem[];
}) {
const hasOutline = outline != null && outline.length > 0;
- const isNarrow = useMediaQuery('(max-width: 1024px)');
+ const isNarrow = useMediaQuery(TOC_BREAKPOINT);
const showAside = hasOutline && !isNarrow;
const showSelector = hasOutline && isNarrow;
@@ -150,7 +179,7 @@ export function DocPageLayout({
<Section
maxWidth={layout.proseMaxWidth}
padding={6}
- xstyle={showAside ? styles.sectionInRow : styles.sectionCentered}>
+ xstyle={hasOutline ? styles.sectionInRow : styles.sectionCentered}>
<VStack gap={10}>
<VStack gap={4}>
<Heading level={1} type="display-1">
@@ -161,9 +190,7 @@ export function DocPageLayout({
{description}
</Text>
) : null}
- {/* When the mobile selector is shown it carries its own bottom border,
- so the title divider is dropped to avoid a doubled separator. */}
- {showSelector ? null : <Divider />}
+ <Divider xstyle={hasOutline && styles.titleDivider} />
</VStack>
{showSelector ? (
<div ref={selectorRef} {...stylex.props(styles.mobileOutline)}>