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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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><Popoverwidth={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 + modetoggle), divider, and the theme picker (one card pertheme). */}- <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={<ThemeActionsselectedPkgName={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)}><Texttype="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 mobilebar lives at the top of this column and takes over for thehidden sidebar at narrow viewports. */}- <div {...stylex.props(styles.rightColumn)}>+ <ThemeExplorerRightColumn>{/* Mobile floating toolbar — hidden until the carousel scrollsout of view, then animates in from below. Contains the themeselector dropdown + mode toggle so users always have accessto 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={<Selectorlabel="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, andaction buttons (Open in Playground + mode toggle). */}- <div {...stylex.props(styles.mobileContext)}>+ <ThemeExplorerMobileContext><ThemeHeadingalign="center"- isMobile={isMobile}+ isMobilemode={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 withthe 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 thepage 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.tsxindex 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 (<SectionmaxWidth={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>- );-}