An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): refine template gallery previews (#6434)
Ernest4720e0f2607a
diff --git a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts b/apps/docsite/src/__tests__/hidden-shadcn-production.test.tsindex 0b6ba0c4bf..bcdc747be9 100644--- a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts+++ b/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts@@ -282,7 +282,7 @@ describeHiddenProduction('hidden production ShadCN discovery', () => {expect(componentUi).toContain("CURRENT_TARGET === 'canary' && pkg && pkgVersion",);- expect(templateUi).toContain("CURRENT_TARGET === 'canary' && (");+ expect(templateUi).not.toMatch(/shadcn/i);expect(registryItemPaths({blocks, templates, showcaseRegistry, exampleRegistry}),).toEqual([]);diff --git a/apps/docsite/src/app/(site)/templates/page.tsx b/apps/docsite/src/app/(site)/templates/page.tsxindex b377975b0f..9988b10fc9 100644--- a/apps/docsite/src/app/(site)/templates/page.tsx+++ b/apps/docsite/src/app/(site)/templates/page.tsx@@ -3,7 +3,7 @@/*** @file Templates gallery index.* @input Uses generated template metadata, URL preview state, live thumbnails, and a lazy preview dialog.- * @output Renders the filterable gallery and loads the query-synced preview dialog on first open.+ * @output Renders a wide, three-column filterable gallery with scaled 1440×900 previews and loads the query-synced preview dialog on first open.* @position Public `/templates` docsite route.*/@@ -29,7 +29,6 @@ import {buildTemplatePreviewHref} from '../../../components/templatePreviewUrl';import {sortTemplatesByTitle} from '../../../components/templateGalleryOrder';import type {TemplatePreviewItem} from '../../../components/TemplatePreviewDialog';import {trackOpenPlayground, trackView} from '../../../lib/analytics';-import {layout} from '../../../layout.stylex';const LazyTemplatePreviewDialog = lazy(() =>import('../../../components/TemplatePreviewDialog').then(module => ({@@ -249,10 +248,7 @@ function TemplatesGallery() {);return (- <Section- maxWidth={layout.contentMaxWidth}- padding={6}- style={{marginInline: 'auto'}}>+ <Section maxWidth={1600} padding={6} style={{marginInline: 'auto'}}><VStack gap={10}>{/* Header */}<VStack gap={6} align="stretch">@@ -276,14 +272,24 @@ function TemplatesGallery() {</VStack>{/* Body */}- <Grid columns={{minWidth: isMobile ? 280 : 360}} gap={4} width="100%">+ <Grid+ columns={{minWidth: isMobile ? 280 : 360, max: 3}}+ gap={6}+ width="100%">{filteredItems.map(item => {- const templateContent = <TemplateThumbnail slug={item.slug} />;+ const templateContent = (+ <TemplateThumbnail+ slug={item.slug}+ renderWidth={1440}+ aspectRatio="16/10"+ />+ );return (<ClickableCardkey={item.slug}padding={0}+ width="100%"maxWidth="100%"label={`Preview ${item.name}`}onClick={() => openPreview(item.slug)}diff --git a/apps/docsite/src/components/TemplatePreviewDialog.tsx b/apps/docsite/src/components/TemplatePreviewDialog.tsxindex 3747f72cab..f6a4e085fa 100644--- a/apps/docsite/src/components/TemplatePreviewDialog.tsx+++ b/apps/docsite/src/components/TemplatePreviewDialog.tsx@@ -9,19 +9,15 @@* display order. Arrow keys (←/→) also navigate; Escape closes.** @input Template metadata, selected index, open state, and navigation callbacks.- * @output A responsive dialog with live preview and template actions.+ * @output A responsive dialog with a 16:10 live preview up to 1440×900 and template actions.* @position Shared preview controller for the templates gallery.*- * The header surfaces template metadata (name, description) on- * the left. All controls cluster on the right of the header: a- * copy-to-clipboard CLI scaffold command, an Open in Playground action,- * and the close button. The row wraps when the controls no longer fit- * beside the title, and the fullscreen (phone) variant stacks the commands- * and the primary action full width, with the close button pinned to the- * top-inline-end corner — the header must never widen the dialog.+ * The header surfaces template metadata (name, description) with the close+ * button. Install commands and the Open in Playground action live in the+ * footer, where the fullscreen (phone) variant stacks them at full width.*- * The preview sits in a padded, framed (border + radius) surface below the- * header. The prev/next arrows are position:fixed inside the top-layer+ * The preview sits in a framed surface with compact spacing below the header.+ * The prev/next arrows are position:fixed inside the top-layer* <dialog>, so they sit in the backdrop gutters outside the dialog box.*/@@ -43,6 +39,7 @@ import {Layout,LayoutHeader,LayoutContent,+ LayoutFooter,} from '@astryxdesign/core/Layout';import {Button} from '@astryxdesign/core/Button';import {Skeleton} from '@astryxdesign/core/Skeleton';@@ -51,15 +48,6 @@ import {Tooltip} from '@astryxdesign/core/Tooltip';import {TemplatePreviewSurface} from './TemplatePreviewSurface';import {buildTemplatePlaygroundHref} from './playgroundLink';import {trackCopy, trackOpenPlayground, trackNavigate} from '../lib/analytics';-import {CURRENT_TARGET} from '../lib/docsVersions';-import {- shadcnRegistryIsPreview,- shadcnRegistryOrigin,-} from '../generated/shadcnRegistry';-import {- shadcnInstallCommand,- shadcnPageItemPath,-} from '../lib/shadcnRegistry.mjs';export interface TemplatePreviewItem {slug: string;@@ -81,13 +69,15 @@ interface TemplatePreviewDialogProps {}const styles = stylex.create({- dialogTall: {- height: '86vh',+ dialogDesktop: {+ height: 'min(1078px, calc(100dvh - 32px))',borderRadius: 'var(--radius-page)',},body: {position: 'relative',display: 'flex',+ alignItems: 'flex-start',+ justifyContent: 'center',height: '100%',minHeight: 0,boxSizing: 'border-box',@@ -96,9 +86,6 @@ const styles = stylex.create({},headerRow: {width: '100%',- // The header never widens the dialog: a long command or a wide action row- // shrinks or truncates instead. Without this the fullscreen dialog's- // clipped body can be scrolled sideways by focus and never scrolled back.maxWidth: '100%',minWidth: 0,position: 'relative' as const,@@ -111,34 +98,25 @@ const styles = stylex.create({position: 'absolute' as const,top: 0,insetInlineEnd: 0,+ flexShrink: 0,},desktopHeaderMeta: {- // Grow into the free space, but keep a readable floor: when the actions- // no longer fit beside a 240px title block the header wraps instead of- // squeezing the title to nothing.flexGrow: 1,flexShrink: 1,- flexBasis: '240px',+ maxWidth: 800,minWidth: 0,},mobileHeaderMeta: {+ maxWidth: 800,minWidth: 0,paddingInlineEnd: 48,},- actionsRow: {+ footerRow: {width: '100%',minWidth: 0,},- // Standard (desktop) header: the action cluster shares one line with the- // title, so it has to be allowed to shrink — otherwise a narrow window- // pushes "Open in Playground" past the dialog edge.- actionsGroup: {- flexShrink: 1,- minWidth: 0,- },- // Command rows and the primary action stack on the fullscreen (mobile)- // header, so each one gets the full width instead of competing for it.commandStack: {+ flexGrow: 1,flexShrink: 1,minWidth: 0,},@@ -188,25 +166,19 @@ const styles = stylex.create({},});-type CopiedCommand = 'astryx' | 'shadcn' | null;+type CopiedCommand = 'astryx' | null;interface TemplatePreviewHeaderProps {item: TemplatePreviewItem;isFullscreen: boolean;- copiedCommand: CopiedCommand;- onCopyCommand: (kind: Exclude<CopiedCommand, null>) => void;onClose: () => void;}function TemplatePreviewHeader({item,isFullscreen,- copiedCommand,- onCopyCommand,onClose,}: TemplatePreviewHeaderProps) {- const playgroundHref = buildTemplatePlaygroundHref(item.slug);-const metadata = (<VStackgap={0.5}@@ -222,7 +194,42 @@ function TemplatePreviewHeader({</VStack>);- const copyButton = (+ const closeButton = (+ <Button+ variant="secondary"+ isIconOnly+ label="Close preview"+ size="lg"+ icon={<Icon icon="close" color="inherit" />}+ onClick={onClose}+ xstyle={isFullscreen ? styles.closeButton : styles.noShrink}+ />+ );++ return (+ <HStack gap={4} vAlign="start" justify="between" xstyle={styles.headerRow}>+ {metadata}+ {closeButton}+ </HStack>+ );+}++interface TemplatePreviewFooterProps {+ item: TemplatePreviewItem;+ isFullscreen: boolean;+ copiedCommand: CopiedCommand;+ onCopyCommand: () => void;+}++function TemplatePreviewFooter({+ item,+ isFullscreen,+ copiedCommand,+ onCopyCommand,+}: TemplatePreviewFooterProps) {+ const playgroundHref = buildTemplatePlaygroundHref(item.slug);++ const installCommands = (<VStack gap={1} xstyle={styles.commandStack}><HStack gap={2} vAlign="center" xstyle={styles.commandGroup}><Text type="supporting" color="secondary" xstyle={styles.commandLabel}>@@ -243,44 +250,10 @@ function TemplatePreviewHeader({color="inherit"/>}- onClick={() => onCopyCommand('astryx')}+ onClick={onCopyCommand}xstyle={styles.noShrink}/></HStack>- {CURRENT_TARGET === 'canary' && (- <HStack gap={2} vAlign="center" xstyle={styles.commandGroup}>- <Text- type="supporting"- color="secondary"- xstyle={styles.commandLabel}>- {shadcnRegistryIsPreview ? 'shadcn preview (expires)' : 'shadcn'}- </Text>- <Code xstyle={styles.commandCode}>- {shadcnInstallCommand(- shadcnPageItemPath(item.slug),- shadcnRegistryOrigin,- )}- </Code>- <Button- variant="ghost"- isIconOnly- size="lg"- label={- copiedCommand === 'shadcn'- ? 'Copied!'- : 'Copy ShadCN install command'- }- icon={- <Icon- icon={copiedCommand === 'shadcn' ? 'check' : 'copy'}- color="inherit"- />- }- onClick={() => onCopyCommand('shadcn')}- xstyle={styles.noShrink}- />- </HStack>- )}</VStack>);@@ -302,44 +275,15 @@ function TemplatePreviewHeader({/>);- const closeButton = (- <Button- variant="secondary"- isIconOnly- label="Close preview"- size="lg"- icon={<Icon icon="close" color="inherit" />}- onClick={onClose}- xstyle={isFullscreen ? styles.closeButton : undefined}- />- );-- // Fullscreen (mobile) stacks the actions: a phone cannot fit the command- // rows and the primary action on one line, and squeezing them there is what- // pushed the header past the viewport.- const actions = isFullscreen ? (- <VStack gap={2} xstyle={styles.actionsRow}>- {copyButton}+ return isFullscreen ? (+ <VStack gap={2} xstyle={styles.footerRow}>+ {installCommands}{playgroundButton}</VStack>) : (- <HStack gap={2} vAlign="center" xstyle={styles.actionsGroup}>- {copyButton}+ <HStack gap={4} vAlign="center" justify="between" xstyle={styles.footerRow}>+ {installCommands}{playgroundButton}- {closeButton}- </HStack>- );-- return isFullscreen ? (- <VStack gap={3} xstyle={styles.headerRow}>- {metadata}- {actions}- {closeButton}- </VStack>- ) : (- <HStack gap={4} vAlign="start" wrap="wrap" xstyle={styles.headerRow}>- {metadata}- {actions}</HStack>);}@@ -430,29 +374,18 @@ export function TemplatePreviewDialog({}const astryxCommand = `npx @astryxdesign/cli template ${current.slug} ./src/app/${current.slug}`;- const shadcnCommand = shadcnInstallCommand(- shadcnPageItemPath(current.slug),- shadcnRegistryOrigin,- );- const handleCopyCmd = useCallback(- (kind: Exclude<CopiedCommand, null>) => {- if (kind === 'shadcn' && CURRENT_TARGET !== 'canary') {- return;- }- const command = kind === 'astryx' ? astryxCommand : shadcnCommand;- navigator.clipboard.writeText(command).then(() => {- setCopiedCommand(kind);- trackCopy({- page: 'templates',- target: kind === 'astryx' ? 'cli_command' : 'install_command',- item: current.slug,- category: current.category,- });- setTimeout(() => setCopiedCommand(null), 2000);+ const handleCopyCmd = useCallback(() => {+ navigator.clipboard.writeText(astryxCommand).then(() => {+ setCopiedCommand('astryx');+ trackCopy({+ page: 'templates',+ target: 'cli_command',+ item: current.slug,+ category: current.category,});- },- [astryxCommand, shadcnCommand, current.slug, current.category],- );+ setTimeout(() => setCopiedCommand(null), 2000);+ });+ }, [astryxCommand, current.slug, current.category]);const isFullscreen = variant === 'fullscreen';@@ -461,19 +394,24 @@ export function TemplatePreviewDialog({isOpen={isOpen}onOpenChange={onOpenChange}variant={variant}- width={isFullscreen ? undefined : 1400}- maxHeight={isFullscreen ? undefined : '92vh'}- xstyle={isFullscreen ? undefined : styles.dialogTall}+ // Scale the desktop dialog with available block space so the preview can+ // stay full-width and 16:10. The offsets account for viewport gutters,+ // fixed header/footer chrome, and the preview's inline padding.+ width={+ isFullscreen+ ? undefined+ : 'min(1472px, calc((100dvh - 210px) * 1.6 + 32px))'+ }+ maxHeight={isFullscreen ? undefined : 'calc(100dvh - 32px)'}+ xstyle={isFullscreen ? undefined : styles.dialogDesktop}aria-label={current.name}><Layoutheight="fill"header={- <LayoutHeader xstyle={styles.dialogHeader}>+ <LayoutHeader paddingBlockEnd={2} xstyle={styles.dialogHeader}><TemplatePreviewHeaderitem={current}isFullscreen={isFullscreen}- copiedCommand={copiedCommand}- onCopyCommand={handleCopyCmd}onClose={() => onOpenChange(false)}/></LayoutHeader>@@ -495,6 +433,16 @@ export function TemplatePreviewDialog({</div></LayoutContent>}+ footer={+ <LayoutFooter>+ <TemplatePreviewFooter+ item={current}+ isFullscreen={isFullscreen}+ copiedCommand={copiedCommand}+ onCopyCommand={handleCopyCmd}+ />+ </LayoutFooter>+ }/>{count > 1 && !isFullscreen && (diff --git a/apps/docsite/src/components/TemplatePreviewSurface.module.css b/apps/docsite/src/components/TemplatePreviewSurface.module.cssindex dfc6ea6357..8128756dc4 100644--- a/apps/docsite/src/components/TemplatePreviewSurface.module.css+++ b/apps/docsite/src/components/TemplatePreviewSurface.module.css@@ -1,14 +1,15 @@/* Copyright (c) Meta Platforms, Inc. and affiliates. */-/* The preview "window". A fixed-height frame (flex-filled by the dialog)- that contains the live template. Fill-mode templates scroll their own- content region; auto-height templates can still fall back to this frame. */+/* The preview "window". It preserves the 1440×900 aspect ratio while fitting+ the dialog body's available width and height. Fill-mode templates scroll+ their own content region; auto-height templates can still use this frame. */.frame {position: relative;- width: 100%;- max-width: 1600px;+ width: min(100%, 1440px);+ max-height: 900px;+ aspect-ratio: 16 / 10;margin-inline: auto;- flex: 1 1 auto;+ flex: 0 0 auto;min-height: 0;/* The frame is the single scroll container. Fill-mode templates fit theframe exactly and scroll their own content region internally (no framediff --git a/apps/docsite/src/components/TemplateThumbnail.tsx b/apps/docsite/src/components/TemplateThumbnail.tsxindex 8a7a5f1686..8be26d347c 100644--- a/apps/docsite/src/components/TemplateThumbnail.tsx+++ b/apps/docsite/src/components/TemplateThumbnail.tsx@@ -3,7 +3,7 @@/*** @file Renders a scaled live template preview inside a gallery tile.* @input Uses the template slug, theme mode, visibility, and measured tile size.- * @output Renders only visible previews and releases the global queue after each committed render.+ * @output Renders visible previews in a normalized viewport and releases the global queue after each committed render.* @position Client-side live preview for template gallery cards.*/@@ -24,6 +24,7 @@ import {neutralTheme} from '@astryxdesign/theme-neutral/built';import {useThemeMode} from '../app/providers';import {TEMPLATE_COMPONENTS} from './templateComponents';import {scheduleThumbnailRender} from './thumbnailRenderScheduler';+import previewCss from './TemplatePreviewSurface.module.css';const FIXED_SCALE = 0.5;@@ -225,8 +226,10 @@ export function TemplateThumbnail({</div>}><Theme theme={neutralTheme} mode={mode}>- <Component />- <ThumbnailRenderSettled onSettled={settleRender} />+ <div className={previewCss.viewport}>+ <Component />+ <ThumbnailRenderSettled onSettled={settleRender} />+ </div></Theme></Suspense></div>