Skip to content

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

TypeScript

fix(docsite): stabilize PPR loading states (#5548)

Xinzi Zhou9da7cb3f5ea9
diff --git a/apps/docsite/src/__tests__/static-shell.test.ts b/apps/docsite/src/__tests__/static-shell.test.ts
new file mode 100644
index 0000000000..850dde8480
--- /dev/null
+++ b/apps/docsite/src/__tests__/static-shell.test.ts
@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the docsite's query-driven PPR boundaries and global footer.
+ * @input Reads the relevant docsite source files
+ * @output Invariants for narrow Suspense boundaries, named fallbacks, and
+ * CSS-driven footer responsiveness
+ * @position Cross-cutting meta-test; no runtime behavior of its own
+ *
+ * The docsite runs with `cacheComponents: true` (Partial Prerendering).
+ * Request state such as `searchParams` is valid, but everything up to its
+ * nearest Suspense boundary becomes a PPR hole. The component detail page and
+ * theme explorer deliberately keep their existing deep-link behavior; these
+ * tests make sure their boundaries stay narrow and never regress to an empty
+ * fallback. The global footer must be CSS-responsive because a JavaScript
+ * media query cannot know the viewport during prerendering.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+
+const SRC_DIR = join(__dirname, '..');
+
+function source(path: string): string {
+ return readFileSync(join(SRC_DIR, path), 'utf8');
+}
+
+describe('docsite static shell', () => {
+ it('keeps the component heading outside the query-dependent boundary', () => {
+ const detail = source(
+ 'components/component-detail/ComponentDetailClient.tsx',
+ );
+
+ expect(detail).toContain('const searchParams = useSearchParams()');
+ expect(detail).toContain(
+ 'fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}',
+ );
+ expect(detail).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
+ expect(detail.indexOf('<Text type="display-1">')).toBeLessThan(
+ detail.indexOf('<Suspense'),
+ );
+ });
+
+ it('reuses the same theme heading in fallback and resolved layouts', () => {
+ const themes = source('app/(site)/themes/page.tsx');
+ const themePage = source('components/ThemePackagePage.tsx');
+ const heading = source('components/ThemeHeading.tsx');
+ const layout = source('components/ThemeExplorerLayout.tsx');
+
+ expect(themes).toContain('const params = await searchParams');
+ expect(themes).toContain('fallback={<ThemeExplorerFallback />}');
+ expect(themes).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
+ expect(themePage).toContain("import {ThemeHeading} from './ThemeHeading'");
+ expect(themes).toContain(
+ "import {ThemeHeading} from '../../../components/ThemeHeading'",
+ );
+ for (const component of [
+ 'ThemeExplorerLayout',
+ 'ThemeExplorerSidebar',
+ 'ThemeExplorerSidebarSurface',
+ 'ThemeExplorerSidebarContent',
+ 'ThemeExplorerActions',
+ 'ThemeExplorerRightColumn',
+ 'ThemeExplorerMobileContext',
+ 'ThemeExplorerMobileCarousel',
+ 'ThemeExplorerMobileCarouselItem',
+ 'ThemeExplorerPreview',
+ ]) {
+ expect(themePage).toContain(`<${component}`);
+ expect(themes).toContain(`<${component}`);
+ }
+ expect(themePage.match(/<ThemeHeading/g)).toHaveLength(2);
+ expect(themes.match(/<ThemeHeading/g)).toHaveLength(2);
+ expect(themePage).toContain('<ThemeExplorerLayout>');
+ expect(themes).toContain(
+ '<ThemeExplorerLayout statusLabel="Loading theme explorer">',
+ );
+ expect(layout).toContain('inert={statusLabel ? true : undefined}');
+ expect(layout).toContain('<VisuallyHidden as="div" role="status">');
+ expect(themePage).not.toContain('useMediaQuery');
+ expect(themePage).toContain('isMobile\n mode={mode}');
+ expect(heading).toContain('<Skeleton width={36} height={36}');
+ expect(heading).toContain('tabIndex={isLoading ? -1 : undefined}');
+ expect(heading).toContain('Astryx comes with a default theme built in');
+ expect(heading).toContain('Learn how theming works');
+ });
+
+ it('the site footer does not branch on a media query', () => {
+ // SiteFooter renders on every route, docs and marketing alike, so it is
+ // part of the static shell at every width. Its responsive layout has to be
+ // CSS (see the MOBILE media query in SiteFooter.tsx), because a JS branch
+ // can only ever prerender one of the two arms.
+ const footer = source('components/SiteFooter.tsx');
+ expect(footer).not.toMatch(
+ /import[^;]*(?:useAppShellMobile|useMediaQuery)[^;]*from/,
+ );
+ });
+});
diff --git a/apps/docsite/src/app/(site)/themes/page.tsx b/apps/docsite/src/app/(site)/themes/page.tsx
index 7258644a00..2d7236a849 100644
--- a/apps/docsite/src/app/(site)/themes/page.tsx
+++ b/apps/docsite/src/app/(site)/themes/page.tsx
@@ -16,12 +16,29 @@
*/
import type {Metadata} from 'next';
+import * as stylex from '@stylexjs/stylex';
import {Suspense} from 'react';
import {notFound} from 'next/navigation';
import {Section} from '@astryxdesign/core/Section';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
+import {Carousel} from '@astryxdesign/core/Carousel';
import {packages} from '../../../generated/packageRegistry';
import {themeObjects} from '../../../generated/themeRegistry';
import {ThemePackagePage} from '../../../components/ThemePackagePage';
+import {ThemeHeading} from '../../../components/ThemeHeading';
+import {
+ ThemeExplorerActions,
+ ThemeExplorerLayout,
+ ThemeExplorerMobileCarousel,
+ ThemeExplorerMobileCarouselItem,
+ ThemeExplorerMobileContext,
+ ThemeExplorerPreview,
+ ThemeExplorerPreviewSkeleton,
+ ThemeExplorerRightColumn,
+ ThemeExplorerSidebar,
+ ThemeExplorerSidebarContent,
+ ThemeExplorerSidebarSurface,
+} from '../../../components/ThemeExplorerLayout';
import {pageMetadata} from '../../../lib/pageMetadata';
// Static canonical metadata for /themes. The page also accepts a `?theme=`
@@ -40,6 +57,12 @@ export const metadata: Metadata = pageMetadata({
// users browse into the more expressive themes (Y2K, Butter, etc.).
const DEFAULT_THEME_PACKAGE = '@astryxdesign/theme-neutral';
+const styles = stylex.create({
+ loadingMobileCarousel: {
+ overflow: 'hidden',
+ },
+});
+
function slugToPackageName(slug: string): string {
return `@astryxdesign/theme-${slug}`;
}
@@ -51,7 +74,7 @@ export default function ThemesPage({
}) {
return (
<Section maxWidth="lg" padding={6}>
- <Suspense fallback={null}>
+ <Suspense fallback={<ThemeExplorerFallback />}>
<SeededThemeExplorer searchParams={searchParams} />
</Suspense>
</Section>
@@ -100,3 +123,71 @@ async function SeededThemeExplorer({
return <ThemePackagePage packageName={seedPkg.name} theme={seedTheme} />;
}
+
+/**
+ * The selected theme is request-dependent, but the page heading is not. Render
+ * the exact same ThemeHeading component at the exact same desktop/mobile
+ * positions as ThemePackagePage, replacing only theme-dependent controls,
+ * cards, and preview content with Skeletons.
+ */
+function ThemeActionsFallback({index = 1}: {index?: number}) {
+ return (
+ <ThemeExplorerActions>
+ <Skeleton width="100%" height={40} index={index} />
+ <Skeleton width="100%" height={40} index={index + 1} />
+ </ThemeExplorerActions>
+ );
+}
+
+function ThemeExplorerFallback() {
+ return (
+ <ThemeExplorerLayout statusLabel="Loading theme explorer">
+ <ThemeExplorerSidebar>
+ <ThemeExplorerSidebarSurface>
+ <ThemeExplorerSidebarContent
+ heading={<ThemeHeading isLoading />}
+ actions={<ThemeActionsFallback />}
+ themes={
+ <>
+ {Array.from({length: 6}, (_, index) => (
+ <Skeleton
+ key={index}
+ width="100%"
+ height={120}
+ index={index + 3}
+ />
+ ))}
+ </>
+ }
+ />
+ </ThemeExplorerSidebarSurface>
+ </ThemeExplorerSidebar>
+
+ <ThemeExplorerRightColumn>
+ <ThemeExplorerMobileContext>
+ <ThemeHeading align="center" isMobile isLoading />
+ <ThemeActionsFallback />
+ </ThemeExplorerMobileContext>
+ <ThemeExplorerMobileCarousel>
+ {mobileCarouselStyle => (
+ <Carousel
+ gap={3}
+ hasButtons={false}
+ hasSnap
+ aria-label="Themes loading"
+ xstyle={[mobileCarouselStyle, styles.loadingMobileCarousel]}>
+ {Array.from({length: 4}, (_, index) => (
+ <ThemeExplorerMobileCarouselItem key={index}>
+ <Skeleton width="100%" height={120} index={index + 3} />
+ </ThemeExplorerMobileCarouselItem>
+ ))}
+ </Carousel>
+ )}
+ </ThemeExplorerMobileCarousel>
+ <ThemeExplorerPreview>
+ <ThemeExplorerPreviewSkeleton index={7} />
+ </ThemeExplorerPreview>
+ </ThemeExplorerRightColumn>
+ </ThemeExplorerLayout>
+ );
+}
diff --git a/apps/docsite/src/components/SiteFooter.tsx b/apps/docsite/src/components/SiteFooter.tsx
index 0948205c1a..40aa6cd9fd 100644
--- a/apps/docsite/src/components/SiteFooter.tsx
+++ b/apps/docsite/src/components/SiteFooter.tsx
@@ -10,7 +10,6 @@ import {HStack, VStack} from '@astryxdesign/core/Layout';
import {Grid, GridSpan} from '@astryxdesign/core/Grid';
import {Divider} from '@astryxdesign/core/Divider';
import {Section} from '@astryxdesign/core/Section';
-import {useAppShellMobile} from '@astryxdesign/core/AppShell';
import {DocsVersionFooterLink} from './DocsVersionFooterLink';
import {
GITHUB_REPO,
@@ -31,6 +30,8 @@ import {
DiscordLogo,
} from './logos';
+const MOBILE = '@media (max-width: 768px)';
+
const styles = stylex.create({
siteFooter: {
// Match the section rhythm above (responsive); fall back off the home page.
@@ -54,8 +55,56 @@ const styles = stylex.create({
display: 'block',
color: 'var(--color-icon-secondary)',
},
+ // Keeps the wrapped link list to a readable measure once it stacks; on
+ // desktop the links sit in their own grid column and must not be clamped.
mobileFooterLinks: {
- maxWidth: 320,
+ maxWidth: {default: 'none', [MOBILE]: 320},
+ },
+ // The footer is one markup at every width — the layout swaps in CSS, not in
+ // JS. It used to branch on `useAppShellMobile().isMobile`, which is a
+ // `useMediaQuery` whose server snapshot is always `false`: the prerendered
+ // HTML therefore carried the DESKTOP grid at every width, so on a phone the
+ // wordmark, the link list and the social buttons all painted on top of each
+ // other in ~80px columns until hydration replaced them. A media query has
+ // the right answer on the very first paint.
+ //
+ // Every override below RESTATES its desktop value in `default` rather than
+ // leaving it `null`. `xstyle` merges after the component's own styles and a
+ // `null` there *unsets* the property, so `{default: null, …}` would strip
+ // VStack's gap and Grid's `display: grid` at desktop width.
+ stack: {
+ // VStack gap={4}
+ gap: {default: 'var(--spacing-4)', [MOBILE]: 'var(--spacing-6)'},
+ },
+ // `grid-template-columns` (from Grid) and `grid-column` (from GridSpan) are
+ // inert under `display: flex`, and `flex-direction` is inert under
+ // `display: grid`, so switching `display` alone turns the row into a
+ // centered column.
+ row: {
+ display: {default: 'grid', [MOBILE]: 'flex'},
+ flexDirection: 'column',
+ alignItems: 'center',
+ },
+ navRow: {
+ gap: {default: 'normal', [MOBILE]: 'var(--spacing-6)'},
+ },
+ legalRow: {
+ gap: {default: 'normal', [MOBILE]: 'var(--spacing-2)'},
+ },
+ navLinks: {
+ // HStack gap={4}
+ gap: {default: 'var(--spacing-4)', [MOBILE]: 'var(--spacing-3)'},
+ },
+ copyright: {
+ // Text justify="end"
+ textAlign: {default: 'end', [MOBILE]: 'center'},
+ },
+ social: {
+ // Must stay `nowrap` on desktop: the social buttons sit in a `1fr` grid
+ // track, and a track only grows past its share to fit its MIN-CONTENT — a
+ // wrappable row has a one-icon min-content, so the track would stay at
+ // 1/5 of the row and the icons would wrap onto a second line.
+ flexWrap: {default: 'nowrap', [MOBILE]: 'wrap'},
},
});
@@ -151,8 +200,6 @@ function LegalLinks() {
}
export function SiteFooter({year}: {year: number}) {
- const {isMobile} = useAppShellMobile();
-
// The regex compliance check requires the year to immediately follow the
// copyright mark — `©{year}`, no separating space. See PR description.
const copyright = `\u00A9${year} Meta Platforms, Inc.`;
@@ -175,61 +222,29 @@ export function SiteFooter({year}: {year: number}) {
</Link>
);
- if (isMobile) {
- // On narrow viewports the horizontal rows can't fit side by side, so we
- // stack the three regions vertically and let the link lists wrap.
- return (
- <Section role="contentinfo" padding={6} xstyle={styles.siteFooter}>
- <VStack gap={6}>
- <VStack gap={6} hAlign="center">
- {astryxLogo}
- <HStack
- gap={3}
- wrap="wrap"
- hAlign="center"
- align="center"
- xstyle={styles.mobileFooterLinks}>
- <NavLinks />
- </HStack>
- <HStack gap={2} wrap="wrap" align="center">
- <SocialButtons />
- </HStack>
- </VStack>
-
- <Divider />
-
- <VStack gap={2} hAlign="center">
- {metaOpenSourceLink}
- <HStack gap={4} hAlign="start" xstyle={styles.mobileFooterLinks}>
- <LegalLinks />
- </HStack>
- <Text type="supporting" color="secondary">
- {copyright}
- </Text>
- </VStack>
- </VStack>
- </Section>
- );
- }
-
return (
<Section role="contentinfo" padding={6} xstyle={styles.siteFooter}>
- <VStack gap={4}>
- <Grid columns={5} align="center">
+ <VStack gap={4} xstyle={styles.stack}>
+ <Grid columns={5} align="center" xstyle={[styles.row, styles.navRow]}>
{astryxLogo}
<GridSpan columns={3}>
- <HStack gap={4} wrap="wrap" align="center" hAlign="center">
+ <HStack
+ gap={4}
+ wrap="wrap"
+ align="center"
+ hAlign="center"
+ xstyle={[styles.navLinks, styles.mobileFooterLinks]}>
<NavLinks />
</HStack>
</GridSpan>
- <HStack gap={2} align="center" justify="end">
+ <HStack gap={2} align="center" justify="end" xstyle={styles.social}>
<SocialButtons />
</HStack>
</Grid>
<Divider />
- <Grid columns={4} align="center">
+ <Grid columns={4} align="center" xstyle={[styles.row, styles.legalRow]}>
{metaOpenSourceLink}
<GridSpan columns={2}>
<HStack
@@ -241,7 +256,11 @@ export function SiteFooter({year}: {year: number}) {
<LegalLinks />
</HStack>
</GridSpan>
- <Text type="supporting" color="secondary" justify="end">
+ <Text
+ type="supporting"
+ color="secondary"
+ justify="end"
+ xstyle={styles.copyright}>
{copyright}
</Text>
</Grid>
diff --git a/apps/docsite/src/components/ThemeExplorerLayout.tsx b/apps/docsite/src/components/ThemeExplorerLayout.tsx
new file mode 100644
index 0000000000..f7b5513d7e
--- /dev/null
+++ b/apps/docsite/src/components/ThemeExplorerLayout.tsx
@@ -0,0 +1,277 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThemeExplorerLayout.tsx
+ * @input Receives the theme explorer's sidebar, mobile controls, carousel, and preview content
+ * @output Shared responsive layout primitives for the resolved explorer and its PPR fallback
+ * @position Single source of truth for Themes desktop/mobile composition
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
+import {Card} from '@astryxdesign/core/Card';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Divider} from '@astryxdesign/core/Divider';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {layout} from '../layout.stylex';
+
+/** Breakpoint shared by the resolved explorer and its loading state. */
+export const THEME_EXPLORER_SIDEBAR_QUERY = '(max-width: 900px)';
+const SIDEBAR_BREAKPOINT = '@media (max-width: 900px)';
+
+const SIDEBAR_WIDTH = 260;
+const SIDEBAR_STICKY_TOP =
+ 'calc(var(--appshell-header-height, 64px) + var(--spacing-4))';
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'flex-start',
+ gap: 'var(--spacing-6)',
+ [SIDEBAR_BREAKPOINT]: {
+ flexDirection: 'column',
+ },
+ },
+ sidebar: {
+ flex: '0 0 auto',
+ width: SIDEBAR_WIDTH,
+ position: 'sticky',
+ top: SIDEBAR_STICKY_TOP,
+ maxHeight: `calc(100dvh - var(--appshell-header-height, 64px) - var(--spacing-4) * 2)`,
+ overflowY: 'auto',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'none',
+ },
+ },
+ sidebarCard: {
+ padding: 'var(--spacing-4)',
+ },
+ themeList: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 'var(--spacing-2)',
+ },
+ rightColumn: {
+ flex: '1 1 0',
+ minWidth: 0,
+ width: '100%',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 'var(--spacing-8)',
+ },
+ mobileContext: {
+ display: 'none',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 'var(--spacing-5)',
+ },
+ },
+ mobileCarousel: {
+ display: 'none',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'flex',
+ width: '100%',
+ },
+ },
+ mobileCarouselItem: {
+ flexShrink: 0,
+ width: 140,
+ },
+ mobileBar: {
+ display: 'none',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'flex',
+ flexDirection: 'row',
+ alignItems: 'center',
+ gap: 'var(--spacing-2)',
+ padding: 'var(--spacing-2)',
+ borderRadius: 'var(--radius-full)',
+ borderWidth: 'var(--border-width)',
+ borderStyle: 'solid',
+ borderColor: 'var(--color-border)',
+ backgroundColor: 'var(--color-background-card)',
+ boxShadow: 'var(--shadow-high)',
+ position: 'fixed',
+ bottom: 'var(--spacing-4)',
+ left: 0,
+ right: 0,
+ marginInline: 'auto',
+ zIndex: 100,
+ width: 'fit-content',
+ maxWidth: `calc(100vw - var(--spacing-4) * 2)`,
+ opacity: 0,
+ pointerEvents: 'none',
+ transition: 'opacity 0.2s ease',
+ },
+ },
+ mobileBarVisible: {
+ [SIDEBAR_BREAKPOINT]: {
+ opacity: 1,
+ pointerEvents: 'auto',
+ },
+ },
+ mobileSelector: {
+ minWidth: 160,
+ },
+ preview: {
+ width: '100%',
+ maxWidth: layout.contentMaxWidth,
+ marginInline: 'auto',
+ overflow: 'hidden',
+ borderRadius: 'var(--radius-container)',
+ },
+ previewSkeleton: {
+ height: {default: 720, [SIDEBAR_BREAKPOINT]: 520},
+ width: '100%',
+ overflow: 'hidden',
+ },
+});
+
+/**
+ * Outer desktop-row/mobile-column shell. A `statusLabel` marks a temporary PPR
+ * fallback: its visual tree becomes inert so no descendant can receive focus,
+ * while a separate visually-hidden status remains available to assistive tech.
+ */
+export function ThemeExplorerLayout({
+ children,
+ statusLabel,
+}: {
+ children: ReactNode;
+ /** Accessible loading label; omitted for the resolved explorer. */
+ statusLabel?: string;
+}) {
+ return (
+ <>
+ {statusLabel && (
+ <VisuallyHidden as="div" role="status">
+ {statusLabel}
+ </VisuallyHidden>
+ )}
+ <div
+ inert={statusLabel ? true : undefined}
+ {...stylex.props(styles.root)}>
+ {children}
+ </div>
+ </>
+ );
+}
+
+/** Sticky desktop sidebar, hidden at the shared mobile breakpoint. */
+export function ThemeExplorerSidebar({children}: {children: ReactNode}) {
+ return (
+ <aside {...stylex.props(styles.sidebar)} aria-label="Theme picker">
+ {children}
+ </aside>
+ );
+}
+
+/** Shared surface treatment inside the desktop sidebar. */
+export function ThemeExplorerSidebarSurface({children}: {children: ReactNode}) {
+ return (
+ <Card variant="default" padding={0} xstyle={styles.sidebarCard}>
+ {children}
+ </Card>
+ );
+}
+
+/**
+ * Shared desktop sidebar internals: heading/actions, divider, and theme list.
+ * Fallback and resolved states supply different content to the same geometry.
+ */
+export function ThemeExplorerSidebarContent({
+ heading,
+ actions,
+ themes,
+}: {
+ heading: ReactNode;
+ actions: ReactNode;
+ themes: ReactNode;
+}) {
+ return (
+ <VStack gap={4}>
+ <VStack gap={5}>
+ {heading}
+ {actions}
+ </VStack>
+ <Divider />
+ <div {...stylex.props(styles.themeList)}>{themes}</div>
+ </VStack>
+ );
+}
+
+/** Shared vertical action cluster for resolved controls and Skeletons. */
+export function ThemeExplorerActions({children}: {children: ReactNode}) {
+ return (
+ <VStack gap={2} align="stretch">
+ {children}
+ </VStack>
+ );
+}
+
+/** Flexible right column containing mobile controls, carousel, and preview. */
+export function ThemeExplorerRightColumn({children}: {children: ReactNode}) {
+ return <div {...stylex.props(styles.rightColumn)}>{children}</div>;
+}
+
+/** Mobile-only heading/actions region above the theme carousel. */
+export function ThemeExplorerMobileContext({children}: {children: ReactNode}) {
+ return <div {...stylex.props(styles.mobileContext)}>{children}</div>;
+}
+
+/** Fixed mobile selector/mode toolbar; hidden until its carousel leaves view. */
+export function ThemeExplorerMobileBar({
+ isVisible,
+ selector,
+ modeToggle,
+}: {
+ isVisible: boolean;
+ selector: ReactNode;
+ modeToggle: ReactNode;
+}) {
+ return (
+ <div
+ {...stylex.props(styles.mobileBar, isVisible && styles.mobileBarVisible)}>
+ <div {...stylex.props(styles.mobileSelector)}>{selector}</div>
+ {modeToggle}
+ </div>
+ );
+}
+
+/**
+ * Shared carousel slot. A render prop applies the responsive style to the
+ * caller's own root, preserving Carousel's scroll and snap DOM geometry.
+ */
+export function ThemeExplorerMobileCarousel({
+ children,
+}: {
+ children: (xstyle: StyleXStyles) => ReactNode;
+}) {
+ return children(styles.mobileCarousel);
+}
+
+/** Fixed-width item geometry shared by real and skeleton mobile carousels. */
+export function ThemeExplorerMobileCarouselItem({
+ children,
+}: {
+ children: ReactNode;
+}) {
+ return <div {...stylex.props(styles.mobileCarouselItem)}>{children}</div>;
+}
+
+/** Width, clipping, and centering shared by real and skeleton previews. */
+export function ThemeExplorerPreview({children}: {children: ReactNode}) {
+ return <div {...stylex.props(styles.preview)}>{children}</div>;
+}
+
+/** Shared responsive loading surface for the selected-theme preview. */
+export function ThemeExplorerPreviewSkeleton({index = 0}: {index?: number}) {
+ return (
+ <div {...stylex.props(styles.previewSkeleton)}>
+ <Skeleton width="100%" height="100%" index={index} />
+ </div>
+ );
+}
diff --git a/apps/docsite/src/components/ThemeHeading.tsx b/apps/docsite/src/components/ThemeHeading.tsx
new file mode 100644
index 0000000000..9a984c602b
--- /dev/null
+++ b/apps/docsite/src/components/ThemeHeading.tsx
@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ThemeHeading.tsx
+ * @input Receives responsive alignment plus optional preview-mode state
+ * @output Renders the shared Themes heading, description, docs link, and mode-control slot
+ * @position Shared by the resolved theme explorer and its PPR fallback so both keep identical geometry
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Moon, Sun} from 'lucide-react';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Link} from '@astryxdesign/core/Link';
+import {Button} from '@astryxdesign/core/Button';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
+
+const styles = stylex.create({
+ titleRow: {
+ width: '100%',
+ },
+ titleText: {
+ flex: 1,
+ minWidth: 0,
+ },
+});
+
+interface ThemeHeadingProps {
+ align?: 'start' | 'center';
+ isMobile?: boolean;
+ /** The fallback keeps its link out of sequential focus before replacement. */
+ isLoading?: boolean;
+ /** Effective preview color mode. Omit while the selected theme is loading. */
+ mode?: 'light' | 'dark';
+ /** Toggles preview color mode. Omit in the PPR fallback. */
+ onToggleMode?: () => void;
+}
+
+/**
+ * Shared page heading for both the real theme explorer and its PPR fallback.
+ * The title, copy, link, spacing, and responsive type stay byte-identical; only
+ * the theme-dependent mode control becomes a same-size skeleton while loading.
+ */
+export function ThemeHeading({
+ align = 'start',
+ isMobile = false,
+ isLoading = false,
+ mode,
+ onToggleMode,
+}: ThemeHeadingProps) {
+ const isCentered = align === 'center';
+ const modeToggleLabel =
+ mode === 'dark'
+ ? 'Switch preview to light mode'
+ : 'Switch preview to dark mode';
+ const modeToggleIcon =
+ mode === 'dark' ? <Sun size={16} /> : <Moon size={16} />;
+ const modeControl: ReactNode = onToggleMode ? (
+ <Button
+ variant="ghost"
+ size="lg"
+ isIconOnly
+ label={modeToggleLabel}
+ tooltip={modeToggleLabel}
+ icon={modeToggleIcon}
+ onClick={onToggleMode}
+ />
+ ) : (
+ <Skeleton width={36} height={36} radius="rounded" />
+ );
+
+ return (
+ <VStack gap={2} hAlign={isCentered ? 'center' : undefined}>
+ <HStack gap={2} vAlign="center" xstyle={styles.titleRow}>
+ <Heading
+ level={1}
+ type={isMobile ? 'display-2' : 'display-3'}
+ justify={align}
+ xstyle={styles.titleText}>
+ Themes
+ </Heading>
+ {modeControl}
+ </HStack>
+ <VStack gap={1} hAlign={isCentered ? 'center' : undefined}>
+ <Text type="body" color="secondary" justify={align}>
+ Astryx comes with a default theme built in. To make it your own, copy
+ any theme you see here into a theme file you own.
+ </Text>
+ <Link
+ type="body"
+ color="secondary"
+ href="/docs/theme"
+ hasUnderline
+ tabIndex={isLoading ? -1 : undefined}>
+ Learn how theming works
+ </Link>
+ </VStack>
+ </VStack>
+ );
+}
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index 2a2e910e94..d8e5eb4f94 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -8,8 +8,8 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {usePathname, useRouter} from 'next/navigation';
import {Sun, Moon} from 'lucide-react';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
-import {Heading, Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
import {Card} from '@astryxdesign/core/Card';
import {Carousel} from '@astryxdesign/core/Carousel';
import {Theme} from '@astryxdesign/core/theme';
@@ -17,22 +17,32 @@ import type {DefinedTheme} from '@astryxdesign/core/theme';
import {Button} from '@astryxdesign/core/Button';
import {CodeBlock} from '@astryxdesign/core/CodeBlock';
import {Popover} from '@astryxdesign/core/Popover';
-import {Link} from '@astryxdesign/core/Link';
import {LinkProvider} from '@astryxdesign/core/Link';
import {SelectableCard} from '@astryxdesign/core/SelectableCard';
import {Selector} from '@astryxdesign/core/Selector';
-import {Divider} from '@astryxdesign/core/Divider';
-import {useMediaQuery} from '@astryxdesign/core/hooks';
import {ThemeShowcaseStore} from '../../../../packages/cli/assets/templates/pages/theme-showcase/page';
import {getThemeShowcaseContent} from './themeShowcaseContent';
import {buildPlaygroundHref} from './playgroundLink';
import {packages} from '../generated/packageRegistry';
-import {layout} from '../layout.stylex';
import {themeObjects} from '../generated/themeRegistry';
import {templates} from '../generated/templateRegistry';
import {trackCopy, trackOpenPlayground, trackToggle} from '../lib/analytics';
import {useThemeMode} from '../app/providers';
import commandBlockStyles from './ThemeCommandBlock.module.css';
+import {ThemeHeading} from './ThemeHeading';
+import {
+ ThemeExplorerActions,
+ ThemeExplorerLayout,
+ ThemeExplorerMobileBar,
+ ThemeExplorerMobileCarousel,
+ ThemeExplorerMobileCarouselItem,
+ ThemeExplorerMobileContext,
+ ThemeExplorerPreview,
+ ThemeExplorerRightColumn,
+ ThemeExplorerSidebar,
+ ThemeExplorerSidebarContent,
+ ThemeExplorerSidebarSurface,
+} from './ThemeExplorerLayout';
// Raw source of the theme-showcase page template (embedded as a string in
// the generated template registry). Used to prepopulate the playground's
@@ -93,14 +103,6 @@ function packageNameToSlug(packageName: string): string {
return packageName.replace(/^@astryxdesign\/theme-/, '');
}
-// Below this viewport width the sidebar collapses to a compact
-// Selector dropdown + inline action row above the preview. The
-// sidebar is hidden via @media at the same breakpoint so the two
-// surfaces don't double-render. Picked so the right pane keeps
-// enough horizontal room for the themed preview's product grid.
-const SIDEBAR_QUERY = '(max-width: 900px)';
-const SIDEBAR_BREAKPOINT = `@media ${SIDEBAR_QUERY}`;
-
// Inert anchor for the showcase preview — preventDefaults clicks so demo
// href="#" links don't scroll the docsite to the top.
function PreviewAnchor({
@@ -118,88 +120,7 @@ function PreviewAnchor({
);
}
-// Fixed sidebar width — compact enough that the right pane gets the
-// lion's share of horizontal space, wide enough to fit the longest
-// theme name, the hero heading + description, and the full-width
-// "Build a custom theme" / "How theming works" CTAs at size="md".
-const SIDEBAR_WIDTH = 260;
-
-// Sticky-top offset for the sidebar. Clears the docsite's sticky
-// AppShell top nav (which uses --appshell-header-height,
-// populated post-hydration) plus a touch of breathing room so the
-// sidebar pill doesn't look glued to the nav's bottom edge.
-const SIDEBAR_STICKY_TOP =
- 'calc(var(--appshell-header-height, 64px) + var(--spacing-4))';
-
const styles = stylex.create({
- // Outer two-column container. Sidebar (fixed width) sits left,
- // right pane (flex:1) holds the existing preview + showcase. The
- // gap keeps the two surfaces from butting against each other.
- // alignItems:flex-start so the sticky sidebar's vertical reference
- // is the column top, not the (potentially shorter) sidebar height.
- twoColumn: {
- display: 'flex',
- flexDirection: 'row' as const,
- alignItems: 'flex-start',
- gap: 'var(--spacing-6)',
- [SIDEBAR_BREAKPOINT]: {
- flexDirection: 'column' as const,
- },
- },
- // Sticky sidebar wrapper. position:sticky keeps the panel in view
- // while the right pane scrolls past; top offset clears the docsite
- // top nav so the sidebar doesn't disappear behind it. flex:0 0 auto
- // pins the width to SIDEBAR_WIDTH; the right pane (flex:1) absorbs
- // any leftover horizontal space. Hidden at narrow viewports — the
- // mobile selector + actions row takes its place above the preview.
- //
- // Caps the sidebar at the viewport height (minus the top nav and
- // matching bottom breathing room) and gives it its own scroll
- // container via overflowY:auto. Without that, the sticky panel
- // tracks the viewport but its own contents extend off the bottom
- // edge — users have to scroll the whole page to the bottom before
- // the rest of the sidebar comes into view. With the cap + inner
- // overflow, the sidebar scrolls independently of the page.
- sidebar: {
- flex: '0 0 auto',
- width: SIDEBAR_WIDTH,
- position: 'sticky' as const,
- top: SIDEBAR_STICKY_TOP,
- maxHeight: `calc(100dvh - var(--appshell-header-height, 64px) - var(--spacing-4) * 2)`,
- overflowY: 'auto' as const,
- [SIDEBAR_BREAKPOINT]: {
- display: 'none',
- },
- },
- // Sidebar card — surface chrome (background, border, radius).
- // Padding is generous-but-compact so the inner action stack +
- // theme list breathe without burning horizontal space the right
- // pane needs.
- sidebarCard: {
- padding: 'var(--spacing-4)',
- },
- // Right column — takes the rest of the horizontal space. The
- // inner preview + showcase blocks keep their own 1200px caps so
- // the right pane just hosts them; it doesn't impose its own
- // width constraint. minWidth:0 lets flex shrink it correctly
- // when the viewport is narrow.
- rightColumn: {
- flex: '1 1 0',
- minWidth: 0,
- width: '100%',
- display: 'flex',
- flexDirection: 'column' as const,
- gap: 'var(--spacing-8)',
- },
- // Theme list — vertical stack of themed cards, one per theme.
- // gap separates each card so the inset accent border of the
- // selected card has breathing room around it (rather than
- // bumping into neighboring cards).
- themeList: {
- display: 'flex',
- flexDirection: 'column' as const,
- gap: 'var(--spacing-2)',
- },
// Make every action button (hero CTAs, mode toggle, Open in Playground)
// stretch to the sidebar width and left-align its label
// (Button's default is centered, which looks off in a vertical
@@ -212,15 +133,6 @@ const styles = stylex.create({
actionButton: {
width: '100%',
},
- // Title row — heading takes the leading flex space (minWidth:0 lets it
- // shrink) so the icon-only mode toggle stays pinned to the trailing edge.
- titleRow: {
- width: '100%',
- },
- titleText: {
- flex: 1,
- minWidth: 0,
- },
// The command snippet in the popover — CodeBlock with container="section"
// (no border/radius of its own), so paint the muted inset here. The extra
// inline-end padding keeps wrapping text clear of the absolutely-positioned
@@ -396,72 +308,7 @@ const styles = stylex.create({
mobileThemeCardLabel: {
fontSize: 20,
},
- // Mobile-only floating toolbar that replaces the sidebar at
- // narrow viewports. position:fixed so it stays pinned to the
- // bottom of the viewport as the user scrolls the right pane;
- // horizontally centered with inset + auto margins instead of
- // transform so CSS-anchor-positioned popovers inside it (like
- // Selector's menu) anchor to the visible trigger location.
- // Floating toolbar — appears when the theme carousel scrolls out of
- // view. Hidden by default (opacity:0, pointer-events:none) and becomes
- // visible when the `data-visible` attribute is set.
- mobileBar: {
- display: 'none',
- [SIDEBAR_BREAKPOINT]: {
- display: 'flex',
- flexDirection: 'row' as const,
- alignItems: 'center',
- gap: 'var(--spacing-2)',
- padding: 'var(--spacing-2)',
- borderRadius: 'var(--radius-full)',
- borderWidth: 'var(--border-width)',
- borderStyle: 'solid',
- borderColor: 'var(--color-border)',
- backgroundColor: 'var(--color-background-card)',
- boxShadow: 'var(--shadow-high)',
- position: 'fixed' as const,
- bottom: 'var(--spacing-4)',
- left: 0,
- right: 0,
- marginInline: 'auto',
- zIndex: 100,
- width: 'fit-content',
- maxWidth: `calc(100vw - var(--spacing-4) * 2)`,
- opacity: 0,
- pointerEvents: 'none' as const,
- transition: 'opacity 0.2s ease',
- },
- },
- // Visible state for the floating toolbar.
- mobileBarVisible: {
- [SIDEBAR_BREAKPOINT]: {
- opacity: 1,
- pointerEvents: 'auto' as const,
- },
- },
- // Mobile selector — fixed minimum so the dropdown trigger has
- // room for the longest theme label without forcing the floating
- // pill to span the entire viewport. No flex:1 here (the parent
- // is fit-content sized, not a stretched row).
- mobileSelector: {
- minWidth: 160,
- },
- // Mobile theme carousel — horizontal row of theme cards. Carousel
- // owns scrolling, snapping, overflow affordances, and scrollbar behavior;
- // this wrapper style only controls breakpoint visibility.
- mobileCarousel: {
- display: 'none',
- [SIDEBAR_BREAKPOINT]: {
- display: 'flex',
- width: '100%',
- },
- },
- // Individual card in the mobile carousel — fixed width so cards
- // are uniformly sized and scroll-snappable.
- mobileCarouselCard: {
- flexShrink: 0,
- width: 140,
- },
+
// Showcase card — clips the theme-showcase template's own
// backgrounds (top nav, sections) to the card's rounded corners.
// The card's default variant supplies the border + radius; the
@@ -469,28 +316,6 @@ const styles = stylex.create({
showcaseCard: {
overflow: 'hidden',
},
- // Caps the showcase at the site's wide-content width and centers it so
- // it doesn't run edge-to-edge on very wide screens. overflow:hidden
- // clips template content that exceeds the width on mobile (e.g.
- // inventory filter rows, tables) to the card's rounded corners.
- showcaseBlock: {
- width: '100%',
- maxWidth: layout.contentMaxWidth,
- marginInline: 'auto',
- overflow: 'hidden',
- borderRadius: 'var(--radius-container)',
- },
- // Mobile-only context heading — shown above the preview at narrow
- // viewports. Includes the heading, description, and action row
- // (Open in Playground + mode toggle) mirroring the sidebar's hero.
- mobileContext: {
- display: 'none',
- [SIDEBAR_BREAKPOINT]: {
- display: 'flex',
- flexDirection: 'column' as const,
- gap: 'var(--spacing-5)',
- },
- },
});
// Per-theme override registry for the picker cards. Themes without
@@ -532,64 +357,6 @@ const PICKER_OVERRIDES: Record<
},
};
-function ThemeHeading({
- align = 'start',
- isMobile = false,
- mode,
- onToggleMode,
-}: {
- align?: 'start' | 'center';
- isMobile?: boolean;
- /** Effective preview color mode — drives the toggle beside the title. */
- mode: 'light' | 'dark';
- /** Toggle the preview color mode. */
- onToggleMode: () => void;
-}) {
- const isCentered = align === 'center';
- const modeToggleLabel =
- mode === 'light'
- ? 'Switch preview to dark mode'
- : 'Switch preview to light mode';
- const modeToggleIcon =
- mode === 'light' ? <Moon size={16} /> : <Sun size={16} />;
-
- return (
- <VStack gap={2} hAlign={isCentered ? 'center' : undefined}>
- {/* Title row — heading takes the leading flex space so the icon-only
- mode toggle stays pinned to the trailing edge. display-3 in the
- 260px sidebar; display-2 in the narrow layout. */}
- <HStack gap={2} vAlign="center" xstyle={styles.titleRow}>
- <Heading
- level={1}
- type={isMobile ? 'display-2' : 'display-3'}
- justify={align}
- xstyle={styles.titleText}>
- Themes
- </Heading>
- <Button
- variant="ghost"
- size="lg"
- isIconOnly
- label={modeToggleLabel}
- tooltip={modeToggleLabel}
- icon={modeToggleIcon}
- onClick={onToggleMode}
- />
- </HStack>
- {/* Body + docs link on its own line below it. */}
- <VStack gap={1} hAlign={isCentered ? 'center' : undefined}>
- <Text type="body" color="secondary" justify={align}>
- Astryx comes with a default theme built in. To make it your own, copy
- any theme you see here into a theme file you own.
- </Text>
- <Link type="body" color="secondary" href="/docs/theme" hasUnderline>
- Learn how theming works
- </Link>
- </VStack>
- </VStack>
- );
-}
-
interface ThemeActionsProps {
selectedPkgName: string;
/** Playground deep link for the selected theme + showcase source. */
@@ -609,7 +376,7 @@ function ThemeActions({selectedPkgName, customizeHref}: ThemeActionsProps) {
const displayName = slug.charAt(0).toUpperCase() + slug.slice(1);
return (
- <VStack gap={2} align="stretch">
+ <ThemeExplorerActions>
<Popover
width={300}
label="Use this theme"
@@ -666,7 +433,7 @@ function ThemeActions({selectedPkgName, customizeHref}: ThemeActionsProps) {
});
}}
/>
- </VStack>
+ </ThemeExplorerActions>
);
}
@@ -707,12 +474,6 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
const carouselRef = useRef<HTMLDivElement>(null);
const [showMobileBar, setShowMobileBar] = useState(false);
- // Narrow-viewport check — the same SIDEBAR_QUERY breakpoint that hides the
- // sidebar and shows the mobile context block. Drives the heading's type so
- // the JS render matches the layout swap (no parallel CSS breakpoint). Server
- // default is desktop (false), matching the sidebar shown on first paint.
- const isMobile = useMediaQuery(SIDEBAR_QUERY);
-
// Show the floating toolbar when the carousel scrolls out of view.
useEffect(() => {
const el = carouselRef.current;
@@ -840,119 +601,91 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
);
return (
- <div {...stylex.props(styles.twoColumn)}>
+ <ThemeExplorerLayout>
{/* Sidebar — sticky on desktop, hidden on narrow viewports
(the mobile bar in the right column takes over). Holds:
hero block (heading + description + Open in Playground CTA + mode
toggle), divider, and the theme picker (one card per
theme). */}
- <aside {...stylex.props(styles.sidebar)} aria-label="Theme picker">
- <Card variant="default" padding={0} xstyle={styles.sidebarCard}>
- <VStack gap={4}>
- {/* Hero block — page-level heading + description + CTAs.
- Heading is display-3 in this sidebar (display-2 wraps in the
- 260px column); the narrow layout uses display-2 (see isMobile).
- CTAs stack full-width. */}
- <VStack gap={5}>
+ <ThemeExplorerSidebar>
+ <ThemeExplorerSidebarSurface>
+ <ThemeExplorerSidebarContent
+ heading={
<ThemeHeading
- isMobile={isMobile}
mode={mode}
onToggleMode={handleToggleModeTracked}
/>
+ }
+ actions={
<ThemeActions
selectedPkgName={selectedPkgName}
customizeHref={customizeHref}
/>
- </VStack>
-
- <Divider />
-
- {/* Theme list — one SelectableCard per theme. Each
- card's inner content is wrapped in <Theme> so the
- background color + heading typography reflect the
- theme it represents, giving users a miniature brand
- preview right in the picker. SelectableCard
- handles selection state (inset accent border),
- aria-selected, and focus chrome. */}
- <div {...stylex.props(styles.themeList)}>
- {themePackages.map(pkg => {
- const cardTheme = themeObjects[pkg.name];
- const isActive = pkg.name === selectedPkgName;
- const label = themeLabel(pkg.displayName) || pkg.displayName;
- // Per-theme bespoke artwork lookup. Themes without an
- // entry render with the default radial-gradient
- // backdrop + default wordmark color; themes WITH an
- // entry get a custom photo background + brand-accent
- // wordmark.
- const override = PICKER_OVERRIDES[pkg.name];
- return (
- <SelectableCard
- key={pkg.name}
- label={`Preview ${label} theme`}
- isSelected={isActive}
- onChange={() => handleSelectPkg(pkg.name)}
- padding={0}
- variant="transparent"
- xstyle={styles.themeCard}>
- {cardTheme ? (
- // Always render mini cards in light mode so the
- // picker reads as a stable swatch palette,
- // even when the user has flipped the preview
- // mode toggle to dark. (The dark-mode brand
- // colors for some themes are much darker,
- // which would make the picker look gloomy.)
- <Theme theme={cardTheme} mode="light">
- <div
- {...stylex.props(
- styles.themedSurface,
- // StyleX's props() walks rest args strictly;
- // pass `false` (not `undefined`) when there's
- // no override so the call doesn't choke.
- override?.surface ?? false,
- )}>
+ }
+ themes={
+ <>
+ {themePackages.map(pkg => {
+ const cardTheme = themeObjects[pkg.name];
+ const isActive = pkg.name === selectedPkgName;
+ const label = themeLabel(pkg.displayName) || pkg.displayName;
+ const override = PICKER_OVERRIDES[pkg.name];
+ return (
+ <SelectableCard
+ key={pkg.name}
+ label={`Preview ${label} theme`}
+ isSelected={isActive}
+ onChange={() => handleSelectPkg(pkg.name)}
+ padding={0}
+ variant="transparent"
+ xstyle={styles.themeCard}>
+ {cardTheme ? (
+ <Theme theme={cardTheme} mode="light">
+ <div
+ {...stylex.props(
+ styles.themedSurface,
+ override?.surface ?? false,
+ )}>
+ <Text
+ type="display-3"
+ weight="bold"
+ xstyle={[
+ styles.themeCardLabel,
+ override?.label ?? false,
+ ]}>
+ {label}
+ </Text>
+ </div>
+ </Theme>
+ ) : (
+ <div {...stylex.props(styles.themedSurface)}>
<Text
type="display-3"
weight="bold"
- xstyle={[
- styles.themeCardLabel,
- override?.label ?? false,
- ]}>
+ xstyle={styles.themeCardLabel}>
{label}
</Text>
</div>
- </Theme>
- ) : (
- <div {...stylex.props(styles.themedSurface)}>
- <Text
- type="display-3"
- weight="bold"
- xstyle={styles.themeCardLabel}>
- {label}
- </Text>
- </div>
- )}
- </SelectableCard>
- );
- })}
- </div>
- </VStack>
- </Card>
- </aside>
+ )}
+ </SelectableCard>
+ );
+ })}
+ </>
+ }
+ />
+ </ThemeExplorerSidebarSurface>
+ </ThemeExplorerSidebar>
{/* Right column — themed preview + card showcase. The mobile
bar lives at the top of this column and takes over for the
hidden sidebar at narrow viewports. */}
- <div {...stylex.props(styles.rightColumn)}>
+ <ThemeExplorerRightColumn>
{/* Mobile floating toolbar — hidden until the carousel scrolls
out of view, then animates in from below. Contains the theme
selector dropdown + mode toggle so users always have access
to theme switching as they scroll the long preview. */}
- <div
- {...stylex.props(
- styles.mobileBar,
- showMobileBar && styles.mobileBarVisible,
- )}>
- <div {...stylex.props(styles.mobileSelector)}>
+ <ThemeExplorerMobileBar
+ isVisible={showMobileBar}
+ selector={
<Selector
label="Theme"
isLabelHidden
@@ -962,25 +695,27 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
value={selectedPkgName}
onChange={handleSelectPkg}
/>
- </div>
- <Button
- variant="ghost"
- size="sm"
- isIconOnly
- label={modeToggleLabel}
- tooltip={modeToggleLabel}
- icon={modeToggleIcon}
- onClick={handleToggleMode}
- />
- </div>
+ }
+ modeToggle={
+ <Button
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ label={modeToggleLabel}
+ tooltip={modeToggleLabel}
+ icon={modeToggleIcon}
+ onClick={handleToggleMode}
+ />
+ }
+ />
{/* Mobile context heading — visible only at narrow viewports.
Mirrors the sidebar's hero: heading, description, and
action buttons (Open in Playground + mode toggle). */}
- <div {...stylex.props(styles.mobileContext)}>
+ <ThemeExplorerMobileContext>
<ThemeHeading
align="center"
- isMobile={isMobile}
+ isMobile
mode={mode}
onToggleMode={handleToggleModeTracked}
/>
@@ -988,68 +723,72 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
selectedPkgName={selectedPkgName}
customizeHref={customizeHref}
/>
- </div>
+ </ThemeExplorerMobileContext>
{/* Mobile theme carousel — horizontal row of theme cards.
When this scrolls out of view, the floating toolbar appears.
Carousel owns scroll behavior and snap affordances. */}
- <Carousel
- ref={carouselRef}
- gap={3}
- hasButtons={false}
- hasSnap
- aria-label="Themes"
- xstyle={styles.mobileCarousel}>
- {themePackages.map(pkg => {
- const cardTheme = themeObjects[pkg.name];
- const isActive = pkg.name === selectedPkgName;
- const label = themeLabel(pkg.displayName) || pkg.displayName;
- const override = PICKER_OVERRIDES[pkg.name];
- return (
- <div key={pkg.name} {...stylex.props(styles.mobileCarouselCard)}>
- <SelectableCard
- label={`Preview ${label} theme`}
- isSelected={isActive}
- onChange={() => handleSelectPkg(pkg.name)}
- padding={0}
- variant="transparent">
- {cardTheme ? (
- <Theme theme={cardTheme} mode="light">
- <div
- {...stylex.props(
- styles.themedSurface,
- override?.surface ?? false,
- )}>
- <Text
- type="display-3"
- weight="bold"
- xstyle={[
- styles.themeCardLabel,
- styles.mobileThemeCardLabel,
- override?.label ?? false,
- ]}>
- {label}
- </Text>
- </div>
- </Theme>
- ) : (
- <div {...stylex.props(styles.themedSurface)}>
- <Text
- type="display-3"
- weight="bold"
- xstyle={[
- styles.themeCardLabel,
- styles.mobileThemeCardLabel,
- ]}>
- {label}
- </Text>
- </div>
- )}
- </SelectableCard>
- </div>
- );
- })}
- </Carousel>
+ <ThemeExplorerMobileCarousel>
+ {mobileCarouselStyle => (
+ <Carousel
+ ref={carouselRef}
+ gap={3}
+ hasButtons={false}
+ hasSnap
+ aria-label="Themes"
+ xstyle={mobileCarouselStyle}>
+ {themePackages.map(pkg => {
+ const cardTheme = themeObjects[pkg.name];
+ const isActive = pkg.name === selectedPkgName;
+ const label = themeLabel(pkg.displayName) || pkg.displayName;
+ const override = PICKER_OVERRIDES[pkg.name];
+ return (
+ <ThemeExplorerMobileCarouselItem key={pkg.name}>
+ <SelectableCard
+ label={`Preview ${label} theme`}
+ isSelected={isActive}
+ onChange={() => handleSelectPkg(pkg.name)}
+ padding={0}
+ variant="transparent">
+ {cardTheme ? (
+ <Theme theme={cardTheme} mode="light">
+ <div
+ {...stylex.props(
+ styles.themedSurface,
+ override?.surface ?? false,
+ )}>
+ <Text
+ type="display-3"
+ weight="bold"
+ xstyle={[
+ styles.themeCardLabel,
+ styles.mobileThemeCardLabel,
+ override?.label ?? false,
+ ]}>
+ {label}
+ </Text>
+ </div>
+ </Theme>
+ ) : (
+ <div {...stylex.props(styles.themedSurface)}>
+ <Text
+ type="display-3"
+ weight="bold"
+ xstyle={[
+ styles.themeCardLabel,
+ styles.mobileThemeCardLabel,
+ ]}>
+ {label}
+ </Text>
+ </div>
+ )}
+ </SelectableCard>
+ </ThemeExplorerMobileCarouselItem>
+ );
+ })}
+ </Carousel>
+ )}
+ </ThemeExplorerMobileCarousel>
{/* Themed preview — the theme-showcase template rendered with
the selected theme, wrapped in a bordered, rounded card so
@@ -1058,7 +797,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
own backgrounds (top nav, sections) to the card's radius.
LinkProvider keeps demo href="#" clicks from scrolling the
page to the top (see PreviewAnchor). */}
- <div {...stylex.props(styles.showcaseBlock)}>
+ <ThemeExplorerPreview>
<Card padding={0} xstyle={styles.showcaseCard}>
<Theme theme={selectedTheme} mode={mode}>
<LinkProvider component={PreviewAnchor}>
@@ -1072,8 +811,8 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
</LinkProvider>
</Theme>
</Card>
- </div>
- </div>
- </div>
+ </ThemeExplorerPreview>
+ </ThemeExplorerRightColumn>
+ </ThemeExplorerLayout>
);
}
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 276ed86b23..d35bb74774 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -9,6 +9,7 @@ import {Heading, Text} from '@astryxdesign/core/Text';
import {VStack} from '@astryxdesign/core/Layout';
import {Section} from '@astryxdesign/core/Section';
import {Card} from '@astryxdesign/core/Card';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
import {Divider} from '@astryxdesign/core';
import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';
import {CodeExampleBlock} from '../CodeExampleBlock';
@@ -64,6 +65,16 @@ const styles = stylex.create({
borderColor: 'var(--color-border-emphasized)',
borderRadius: 'var(--radius-container)',
},
+ // Reserve enough of the article to keep the footer below the viewport while
+ // Next streams the query-dependent tab panel. The named skeleton shapes
+ // mirror the tab row, live preview, heading and prose rather than presenting
+ // the empty Suspense hole that previously caused the 0.23 CLS.
+ loadingContent: {
+ minHeight: {default: 900, '@media (max-width: 768px)': 680},
+ },
+ loadingPreview: {
+ height: {default: 320, '@media (max-width: 768px)': 220},
+ },
});
interface ComponentDetailClientProps {
@@ -154,30 +165,35 @@ function OverviewContent({
);
}
-function ComponentDetailInner({
+interface ComponentDetailTabsProps extends ComponentDetailClientProps {
+ hasPlayground: boolean;
+ hasThemingTab: boolean;
+ hasAccessibilityTab: boolean;
+ hasShowcase: boolean;
+}
+
+/**
+ * Query-dependent portion of the page. Keeping this below the nearest
+ * Suspense boundary lets the page heading and every component with no tabs
+ * remain in the prerendered shell while preserving `useSearchParams()` as the
+ * source of truth for deep links and soft navigation.
+ */
+function ComponentDetailTabs({
comp,
pkg,
pkgVersion,
showcase,
-}: ComponentDetailClientProps) {
+ hasPlayground,
+ hasThemingTab,
+ hasAccessibilityTab,
+ hasShowcase,
+}: ComponentDetailTabsProps) {
const searchParams = useSearchParams();
const router = useRouter();
const pathname = usePathname();
-
- const hasShowcase = comp.name in showcaseRegistry;
- const hasPlayground = hasInteractivePlayground(comp);
- // Theming lives in its own tab, shown only on the canary line (where the
- // experimental theming API is documented) and only when the component has
- // themeable targets or CSS variables — never an empty tab.
- const hasThemingTab =
- CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
const accessibilityRequirements = comp.usage?.accessibility ?? [];
const accessibilityThemeCoverage =
comp.usage?.accessibilityThemeCoverage ?? [];
- const hasAccessibilityTab =
- accessibilityRequirements.length > 0 ||
- accessibilityThemeCoverage.length > 0;
- const hasTabs = hasPlayground || hasThemingTab || hasAccessibilityTab;
const requestedTab = searchParams.get('tab') ?? 'overview';
// Clamp to a tab that actually exists for this component so a stale or
@@ -211,6 +227,119 @@ function ComponentDetailInner({
comp.playground,
);
+ return (
+ <>
+ <TabList value={tab} onChange={setTab} hasDivider>
+ <Tab value="overview" label="Overview" />
+ {hasPlayground && <Tab value="properties" label="Properties" />}
+ {hasThemingTab && <Tab value="theming" label="Theming" />}
+ {hasAccessibilityTab && (
+ <Tab value="accessibility" label="Accessibility" />
+ )}
+ </TabList>
+
+ {tab === 'overview' && (
+ <OverviewContent
+ comp={comp}
+ pkg={pkg}
+ pkgVersion={pkgVersion}
+ showcase={showcase}
+ hasShowcase={hasShowcase}
+ />
+ )}
+
+ {tab === 'properties' && hasPlayground && (
+ <VStack gap={4}>
+ <div {...stylex.props(styles.previewStage)}>
+ <InteractivePreviewStage
+ name={comp.name}
+ state={state}
+ knobs={knobs}
+ playground={comp.playground}
+ missingRequiredProps={missingRequiredProps}
+ onPropChange={setProp}
+ embedded
+ canControlOpenState={
+ comp.props.some(prop => prop.name === 'isOpen') &&
+ comp.props.some(prop => prop.name === 'onOpenChange')
+ }
+ />
+ </div>
+
+ {comp.props.length > 0 && (
+ <Section>
+ <VStack gap={3}>
+ <Heading level={3}>Props</Heading>
+ <PlaygroundPropsTable
+ props={comp.props}
+ typeDefs={comp.typeDefs}
+ knobs={knobs}
+ state={state}
+ onPropChange={setProp}
+ />
+ </VStack>
+ </Section>
+ )}
+ </VStack>
+ )}
+
+ {tab === 'theming' && comp.theming && (
+ <Theming theming={comp.theming} props={comp.props} />
+ )}
+
+ {tab === 'accessibility' && hasAccessibilityTab && (
+ <Accessibility
+ componentName={comp.name}
+ requirements={accessibilityRequirements}
+ themeCoverage={accessibilityThemeCoverage}
+ />
+ )}
+ </>
+ );
+}
+
+function ComponentDetailFallback({hasShowcase}: {hasShowcase: boolean}) {
+ return (
+ <div
+ role="status"
+ aria-label="Loading component documentation"
+ {...stylex.props(styles.loadingContent)}>
+ <VStack gap={8}>
+ <Skeleton width="100%" height={40} radius={0} index={0} />
+ {hasShowcase && (
+ <div {...stylex.props(styles.loadingPreview)}>
+ <Skeleton width="100%" height="100%" index={1} />
+ </div>
+ )}
+ <VStack gap={3}>
+ <Skeleton width={180} height={32} index={2} />
+ <Skeleton width="92%" height={18} index={3} />
+ <Skeleton width="68%" height={18} index={4} />
+ <Skeleton width="100%" height={72} index={5} />
+ </VStack>
+ </VStack>
+ </div>
+ );
+}
+
+export function ComponentDetailClient({
+ comp,
+ pkg,
+ pkgVersion,
+ showcase,
+}: ComponentDetailClientProps) {
+ const hasShowcase = comp.name in showcaseRegistry;
+ const hasPlayground = hasInteractivePlayground(comp);
+ const hasThemingTab =
+ CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
+ const accessibilityRequirements = comp.usage?.accessibility ?? [];
+ const accessibilityThemeCoverage =
+ comp.usage?.accessibilityThemeCoverage ?? [];
+ const hasAccessibilityTab =
+ accessibilityRequirements.length > 0 ||
+ accessibilityThemeCoverage.length > 0;
+ const hasTabs = hasPlayground || hasThemingTab || hasAccessibilityTab;
+
return (
<Section
maxWidth={960}
@@ -218,6 +347,8 @@ function ComponentDetailInner({
variant="transparent"
xstyle={styles.section}>
<VStack gap={4}>
+ {/* This heading is independent of the URL and belongs in the static
+ shell. Only the tab row and panel below need request state. */}
<VStack gap={2}>
<Text type="display-1">{comp.displayName}</Text>
<Text type="supporting" color="secondary">
@@ -227,73 +358,19 @@ function ComponentDetailInner({
</VStack>
{hasTabs ? (
- <>
- <TabList value={tab} onChange={setTab} hasDivider>
- <Tab value="overview" label="Overview" />
- {hasPlayground && <Tab value="properties" label="Properties" />}
- {hasThemingTab && <Tab value="theming" label="Theming" />}
- {hasAccessibilityTab && (
- <Tab value="accessibility" label="Accessibility" />
- )}
- </TabList>
-
- {tab === 'overview' && (
- <OverviewContent
- comp={comp}
- pkg={pkg}
- pkgVersion={pkgVersion}
- showcase={showcase}
- hasShowcase={hasShowcase}
- />
- )}
-
- {tab === 'properties' && hasPlayground && (
- <VStack gap={4}>
- <div {...stylex.props(styles.previewStage)}>
- <InteractivePreviewStage
- name={comp.name}
- state={state}
- knobs={knobs}
- playground={comp.playground}
- missingRequiredProps={missingRequiredProps}
- onPropChange={setProp}
- embedded
- canControlOpenState={
- comp.props.some(prop => prop.name === 'isOpen') &&
- comp.props.some(prop => prop.name === 'onOpenChange')
- }
- />
- </div>
-
- {comp.props.length > 0 && (
- <Section>
- <VStack gap={3}>
- <Heading level={3}>Props</Heading>
- <PlaygroundPropsTable
- props={comp.props}
- typeDefs={comp.typeDefs}
- knobs={knobs}
- state={state}
- onPropChange={setProp}
- />
- </VStack>
- </Section>
- )}
- </VStack>
- )}
-
- {tab === 'theming' && comp.theming && (
- <Theming theming={comp.theming} props={comp.props} />
- )}
-
- {tab === 'accessibility' && hasAccessibilityTab && (
- <Accessibility
- componentName={comp.name}
- requirements={accessibilityRequirements}
- themeCoverage={accessibilityThemeCoverage}
- />
- )}
- </>
+ <Suspense
+ fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}>
+ <ComponentDetailTabs
+ comp={comp}
+ pkg={pkg}
+ pkgVersion={pkgVersion}
+ showcase={showcase}
+ hasPlayground={hasPlayground}
+ hasThemingTab={hasThemingTab}
+ hasAccessibilityTab={hasAccessibilityTab}
+ hasShowcase={hasShowcase}
+ />
+ </Suspense>
) : (
<>
<Divider />
@@ -310,11 +387,3 @@ function ComponentDetailInner({
</Section>
);
}
-
-export function ComponentDetailClient(props: ComponentDetailClientProps) {
- return (
- <Suspense>
- <ComponentDetailInner {...props} />
- </Suspense>
- );
-}