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.cssindex 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 frostdiff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsxindex 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.tsxindex 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({<SectionmaxWidth={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)}>