Skip to content

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.ts
index 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.tsx
index 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 (
<ClickableCard
key={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.tsx
index 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 = (
<VStack
gap={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}>
<Layout
height="fill"
header={
- <LayoutHeader xstyle={styles.dialogHeader}>
+ <LayoutHeader paddingBlockEnd={2} xstyle={styles.dialogHeader}>
<TemplatePreviewHeader
item={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.css
index 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 the
frame exactly and scroll their own content region internally (no frame
diff --git a/apps/docsite/src/components/TemplateThumbnail.tsx b/apps/docsite/src/components/TemplateThumbnail.tsx
index 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>