Skip to content

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

TypeScript

fix(docsite): Unified playground fixes (#2739)

Kenton Quatman32c76c87400e
diff --git a/apps/docsite/src/app/playground/ConfirmDialog.tsx b/apps/docsite/src/app/playground/ConfirmDialog.tsx
new file mode 100644
index 0000000000..bca0c13bec
--- /dev/null
+++ b/apps/docsite/src/app/playground/ConfirmDialog.tsx
@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ConfirmDialog.tsx
+ * @input isOpen flag, title, message, confirm/cancel handlers + labels
+ * @output A small confirmation dialog (XDSDialog) with Cancel/Continue actions
+ * @position Playground — shared confirm prompt for destructive playground
+ * actions (loading templates, applying example themes) that overwrite the
+ * user's current code or theme.
+ */
+
+import {type ReactNode} from 'react';
+import {XDSButton} from '@xds/core/Button';
+import {
+ XDSHStack,
+ XDSLayout,
+ XDSLayoutContent,
+ XDSLayoutFooter,
+} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSDialog, XDSDialogHeader} from '@xds/core/Dialog';
+
+export interface ConfirmDialogProps {
+ /** Whether the dialog is open. */
+ isOpen: boolean;
+ /** Dialog title shown in the header. */
+ title: string;
+ /** Body message explaining the consequence of continuing. */
+ message: ReactNode;
+ /** Label for the confirming action. */
+ confirmLabel?: string;
+ /** Label for the dismissing action. */
+ cancelLabel?: string;
+ /** Called when the user confirms the action. */
+ onConfirm: () => void;
+ /** Called when the user cancels or otherwise dismisses the dialog. */
+ onCancel: () => void;
+}
+
+export function ConfirmDialog({
+ isOpen,
+ title,
+ message,
+ confirmLabel = 'Continue',
+ cancelLabel = 'Cancel',
+ onConfirm,
+ onCancel,
+}: ConfirmDialogProps) {
+ return (
+ <XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => {
+ if (!open) {
+ onCancel();
+ }
+ }}
+ purpose="form"
+ width={440}>
+ <XDSLayout
+ header={<XDSDialogHeader title={title} onOpenChange={onCancel} />}
+ content={
+ <XDSLayoutContent>
+ <XDSText type="body" color="secondary">
+ {message}
+ </XDSText>
+ </XDSLayoutContent>
+ }
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSHStack gap={2} justify="end" width="100%">
+ <XDSButton
+ variant="secondary"
+ label={cancelLabel}
+ onClick={onCancel}
+ />
+ <XDSButton
+ variant="primary"
+ label={confirmLabel}
+ onClick={onConfirm}
+ />
+ </XDSHStack>
+ </XDSLayoutFooter>
+ }
+ />
+ </XDSDialog>
+ );
+}
+
+ConfirmDialog.displayName = 'ConfirmDialog';
diff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsx
index d22ba030ce..7e5cf3a767 100644
--- a/apps/docsite/src/app/playground/PlaygroundClient.tsx
+++ b/apps/docsite/src/app/playground/PlaygroundClient.tsx
@@ -31,6 +31,8 @@ import {
decompressFromEncodedURIComponent,
} from 'lz-string';
import {XDSButton} from '@xds/core/Button';
+import {XDSPopover} from '@xds/core/Popover';
+import {XDSTextInput} from '@xds/core/TextInput';
import {XDSLink} from '@xds/core/Link';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSText, XDSHeading} from '@xds/core/Text';
@@ -54,6 +56,10 @@ import {
Maximize2,
RotateCw,
Crosshair,
+ ExternalLink,
+ Copy,
+ Check,
+ Download,
} from 'lucide-react';
import githubLight from './themes/github-light.json';
import githubDark from './themes/github-dark.json';
@@ -65,16 +71,26 @@ import {
} from './playgroundThemes';
import {templates} from '../../generated/templateRegistry';
import {PreviewStage, type Viewport} from './PreviewStage';
+import {ConfirmDialog} from './ConfirmDialog';
import {BRAND_ICON} from '../../components/XDSWordmark';
import {PropertyPanel} from './PropertyPanel';
import {annotateInstanceIds} from './babelParser';
import {trackCopy} from '../../lib/analytics';
import {PlaygroundThemeEditor} from '../../components/themePlayground/PlaygroundThemeEditor';
+import {generateThemeCode} from '../../components/themePlayground/helpers';
import {DEFAULT_CODE} from './defaultCode';
import {stripCodeExampleCopyrightHeader} from '../../lib/codeExamples';
import type * as MonacoTypes from 'monaco-editor';
import type {XDSDefinedTheme} from '@xds/core/theme';
+import {xdsTokenDefaults} from '@xds/core/theme';
+
+// Source of the theme-showcase template — a set of real product surfaces
+// (store, checkout, chat, inventory) used to preview a theme. It's hidden
+// from the generated templates registry (isHiddenFromOverview), so it's added
+// explicitly as the first entry in the Templates dropdown.
+const THEME_SHOWCASE_SOURCE =
+ templates.find(t => t.slug === 'theme-showcase')?.source ?? '';
// Self-host Monaco from public/monaco/vs — corpnet blocks the default
// jsdelivr CDN. Configure the singleton loader before the editor initializes.
@@ -280,6 +296,12 @@ const s = stylex.create({
hidden: {
display: 'none',
},
+ shareInput: {
+ width: 300,
+ },
+ popoverPadding: {
+ padding: 'var(--spacing-4)',
+ },
navGroup: {
gap: 'var(--spacing-2)',
},
@@ -362,7 +384,7 @@ export function PlaygroundClient() {
rawThemeParam && rawThemeParam in themeByValue ? rawThemeParam : null;
const theme = themeParam ?? DEFAULT_PLAYGROUND_THEME;
// The theme whose values seed the Theme editor: the ?theme= theme on first
- // load, then whichever theme the user picks from the "Apply Theme" dropdown.
+ // load, then whichever theme the user picks from the "Themes" dropdown.
// Changing it remounts the editor (via key) so it re-populates from that theme.
const [selectedTheme, setSelectedTheme] = useState(theme);
// The theme object the editor is seeded from. Always defined so the always-
@@ -376,12 +398,35 @@ export function PlaygroundClient() {
const [buildStatus, setBuildStatus] = useState<BuildStatus>('idle');
const [statusFading, setStatusFading] = useState(false);
const [copied, setCopied] = useState(false);
+ const [shareUrl, setShareUrl] = useState('');
+ const [themeName, setThemeName] = useState('');
+ // Snapshot of the theme to export, captured when the Export popover opens.
+ // The live theme lives in customThemeRef (a ref, updated as the user edits
+ // tokens without re-rendering the playground); we copy it into state on
+ // open so the download link below can be built declaratively from reactive
+ // state. The popover is in the toolbar, so the theme isn't being edited
+ // while it's open — the snapshot stays current.
+ const [exportTheme, setExportTheme] = useState<XDSDefinedTheme | null>(null);
const [previewReady, setPreviewReady] = useState(false);
const [isTargeting, setIsTargeting] = useState(false);
const [targetedComponent, setTargetedComponent] = useState<string | null>(
null,
);
const [targetedInstance, setTargetedInstance] = useState(0);
+ // The theme value awaiting confirmation from the "Example themes" dropdown.
+ // Applying an example theme re-seeds the Theme editor and discards the
+ // current theme, so we hold the pending choice until the user confirms.
+ // The dialog is open whenever this is non-null.
+ const [pendingExampleTheme, setPendingExampleTheme] = useState<string | null>(
+ null,
+ );
+ // The template source awaiting confirmation from the "Templates" dropdown.
+ // Loading a template overwrites the code editor, so we hold the pending
+ // choice until the user confirms. The dialog is open whenever this is
+ // non-null.
+ const [pendingTemplateSource, setPendingTemplateSource] = useState<
+ string | null
+ >(null);
const iframeRef = useRef<HTMLIFrameElement>(null);
const readyRef = useRef(false);
@@ -390,6 +435,10 @@ export function PlaygroundClient() {
const editorRef = useRef<MonacoTypes.editor.IStandaloneCodeEditor | null>(
null,
);
+ // Points at the declaratively-rendered theme-export download link (below).
+ // The Download button triggers it so we get native download behavior from a
+ // normally-rendered <a> rather than fabricating one in a click handler.
+ const downloadLinkRef = useRef<HTMLAnchorElement>(null);
// Mirror activeView in a ref so onMount can read the current view without
// re-creating the (stable) mount callback.
const activeViewRef = useRef(activeView);
@@ -427,6 +476,22 @@ export function PlaygroundClient() {
return () => window.removeEventListener('hashchange', onHashChange);
}, []);
+ // Re-read the hash once on mount. When arriving via a soft (client-side)
+ // navigation — e.g. the Themes page's "Open in Playground" link routed
+ // through Next's <Link> — the App Router commits the new URL slightly
+ // after this component first renders, so the synchronous getInitialCode()
+ // seed for `code` above can miss the fragment and fall back to
+ // DEFAULT_CODE. A hashchange event isn't emitted for that navigation
+ // (the page itself changes, not just the fragment), so we read the
+ // committed hash here, after mount, and adopt the seeded code if present.
+ useEffect(() => {
+ const seeded = getInitialCode();
+ if (seeded !== DEFAULT_CODE) {
+ setCode(prev => (prev === seeded ? prev : seeded));
+ }
+ // Runs once on mount; the hashchange listener above covers later changes.
+ }, []);
+
// When a ?theme= param seeds the playground, open the Theme view so the
// populated theme editor is visible (and drives the preview) on arrival.
// Done in an effect (not the initial activeView state) to avoid an
@@ -655,6 +720,34 @@ export function PlaygroundClient() {
});
}, []);
+ // Derive the export href from reactive state so the download is a real,
+ // normally-rendered <a> (see downloadLinkRef below) rather than a DOM
+ // element fabricated and clicked inside a callback. The active theme is the
+ // one authored in the Theme editor (snapshotted into state when the popover
+ // opens), falling back to the seeded theme. Returns the suggested filename
+ // and a data: URL holding the generated `defineTheme` source; null until a
+ // theme name is entered.
+ const themeExport = useMemo(() => {
+ const name = themeName.trim();
+ if (!name) {
+ return null;
+ }
+ const activeTheme = exportTheme ?? editorInitialTheme;
+ const source = generateThemeCode(
+ name,
+ activeTheme.tokens,
+ xdsTokenDefaults,
+ 14,
+ 1.2,
+ [],
+ activeTheme.components ?? {},
+ );
+ return {
+ filename: `${name}-theme.ts`,
+ href: `data:text/typescript;charset=utf-8,${encodeURIComponent(source)}`,
+ };
+ }, [themeName, exportTheme, editorInitialTheme]);
+
const handleMonacoBeforeMount = useCallback((monaco: MonacoInstance) => {
monaco.editor.defineTheme('github-light', githubLight);
monaco.editor.defineTheme('github-dark', githubDark);
@@ -702,26 +795,32 @@ export function PlaygroundClient() {
});
}, []);
- // Dropdown items for "Apply Theme" — derived from the registered playground
+ // Dropdown items for "Themes" — derived from the registered playground
// themes (PLAYGROUND_THEME_OPTIONS) so any installed @xds/theme-* package
- // shows up automatically. Selecting one re-seeds the Theme editor (and thus
- // the preview) with that theme's values.
+ // shows up automatically. Selecting one prompts for confirmation (it discards
+ // the current theme) before re-seeding the Theme editor (and thus the preview)
+ // with that theme's values.
const themeMenuItems = useMemo(
() =>
PLAYGROUND_THEME_OPTIONS.map(option => ({
label: option.label,
- onClick: () => setSelectedTheme(option.value),
+ onClick: () => setPendingExampleTheme(option.value),
})),
[],
);
// Dropdown items for "Templates" — the published, ready templates from the
// generated registry (the same source the /templates gallery renders), so any
- // new template shows up automatically. Selecting one loads its source into the
- // editor (setCode drives Monaco, the preview, and the URL hash).
+ // new template shows up automatically. Selecting one prompts for confirmation
+ // (it overwrites the editor) before loading its source (setCode drives Monaco,
+ // the preview, and the URL hash).
const templateMenuItems = useMemo(
- () =>
- templates
+ () => [
+ {
+ label: 'Theme Showcase',
+ onClick: () => setPendingTemplateSource(THEME_SHOWCASE_SOURCE),
+ },
+ ...templates
.filter(t => !t.isHiddenFromOverview && t.isReady && t.source)
.map(t => {
const dash = t.category.indexOf(' - ');
@@ -735,11 +834,9 @@ export function PlaygroundClient() {
.sort((a, b) => a.label.localeCompare(b.label))
.map(({label, source}) => ({
label,
- onClick: () => {
- setCode(stripCodeExampleCopyrightHeader(source));
- requestAnimationFrame(() => editorRef.current?.focus());
- },
+ onClick: () => setPendingTemplateSource(source),
})),
+ ],
[],
);
@@ -823,34 +920,26 @@ export function PlaygroundClient() {
align="center"
xstyle={s.leftPanelHeader}>
<XDSHeading level={3}>Playground</XDSHeading>
- {activeView === 'code' && (
- <XDSHStack gap={2} align="center">
- <XDSDropdownMenu
- button={{
- label: 'Templates',
- variant: 'secondary',
- size: 'sm',
- }}
- hasChevron
- items={templateMenuItems}
- />
- <XDSButton variant="secondary" size="sm" label="Copy Code" />
- </XDSHStack>
- )}
- {activeView === 'theme' && (
- <XDSHStack gap={2} align="center">
- <XDSDropdownMenu
- button={{
- label: 'Apply Theme',
- variant: 'secondary',
- size: 'sm',
- }}
- hasChevron
- items={themeMenuItems}
- />
- <XDSButton variant="secondary" size="sm" label="Export Theme" />
- </XDSHStack>
- )}
+ <XDSHStack gap={2} align="center">
+ <XDSDropdownMenu
+ button={{
+ label: 'Themes',
+ variant: 'secondary',
+ size: 'md',
+ }}
+ hasChevron
+ items={themeMenuItems}
+ />
+ <XDSDropdownMenu
+ button={{
+ label: 'Templates',
+ variant: 'secondary',
+ size: 'md',
+ }}
+ hasChevron
+ items={templateMenuItems}
+ />
+ </XDSHStack>
</XDSHStack>
<div {...stylex.props(s.tabBody)}>
{/* Code: Monaco stays mounted to preserve typedefs + editor state */}
@@ -1005,12 +1094,104 @@ export function PlaygroundClient() {
)}
</div>
)}
- <XDSButton
- label={copied ? '✓ Copied' : 'Share'}
- variant="primary"
- size="md"
- onClick={handleShare}
- />
+ <XDSPopover
+ label="Share template"
+ placement="below"
+ alignment="end"
+ xstyle={s.popoverPadding}
+ onOpenChange={open => {
+ if (open) {
+ setShareUrl(window.location.href);
+ // Snapshot the live (ref-held) theme so the download
+ // link below can derive its href from reactive state.
+ setExportTheme(
+ customThemeRef.current ?? editorInitialTheme,
+ );
+ }
+ }}
+ content={
+ <XDSVStack gap={6}>
+ <XDSVStack gap={2}>
+ <XDSText type="label" weight="semibold">
+ Share Playground
+ </XDSText>
+ <XDSHStack gap={2} vAlign="center" width="100%">
+ <XDSTextInput
+ label="Share URL"
+ isLabelHidden
+ isDisabled
+ value={shareUrl}
+ onChange={() => {}}
+ xstyle={s.shareInput}
+ />
+ <XDSButton
+ label={copied ? 'Copied' : 'Copy URL'}
+ tooltip={copied ? 'Copied' : 'Copy URL'}
+ variant="secondary"
+ size="md"
+ isIconOnly
+ icon={
+ copied ? <Check size={16} /> : <Copy size={16} />
+ }
+ onClick={handleShare}
+ />
+ </XDSHStack>
+ </XDSVStack>
+ <XDSVStack gap={2}>
+ <XDSText type="label" weight="semibold">
+ Export Theme File
+ </XDSText>
+ <XDSHStack gap={2} vAlign="center" width="100%">
+ <XDSTextInput
+ label="Theme name"
+ isLabelHidden
+ placeholder="Enter theme name"
+ value={themeName}
+ onChange={v =>
+ setThemeName(v.replace(/[\s-]/g, ''))
+ }
+ xstyle={s.shareInput}
+ />
+ <XDSButton
+ label="Download theme"
+ tooltip="Download theme"
+ variant="secondary"
+ size="md"
+ isIconOnly
+ isDisabled={themeExport == null}
+ icon={<Download size={16} />}
+ onClick={() => downloadLinkRef.current?.click()}
+ />
+ {/* The real download target: a normally-rendered
+ link whose href/download come from reactive
+ state. The button above clicks it, so the
+ browser performs a native download without us
+ fabricating an <a> in the handler. */}
+ {themeExport && (
+ <a
+ ref={downloadLinkRef}
+ href={themeExport.href}
+ download={themeExport.filename}
+ {...stylex.props(s.hidden)}
+ aria-hidden="true"
+ tabIndex={-1}>
+ Download theme file
+ </a>
+ )}
+ </XDSHStack>
+ <XDSLink href="/docs/theme" hasUnderline>
+ Learn about using themes
+ </XDSLink>
+ </XDSVStack>
+ </XDSVStack>
+ }>
+ <XDSButton
+ label="Export"
+ variant="primary"
+ size="md"
+ endContent={<ExternalLink size={16} />}
+ />
+ </XDSPopover>
</XDSHStack>
}
/>
@@ -1023,6 +1204,32 @@ export function PlaygroundClient() {
/>
</XDSVStack>
</XDSHStack>
+
+ <ConfirmDialog
+ isOpen={pendingExampleTheme != null}
+ title="Apply example theme"
+ message="Applying an example theme will overwrite your current theme. Any changes you've made in the Theme editor will be lost. Do you want to continue?"
+ onCancel={() => setPendingExampleTheme(null)}
+ onConfirm={() => {
+ if (pendingExampleTheme != null) {
+ setSelectedTheme(pendingExampleTheme);
+ }
+ setPendingExampleTheme(null);
+ }}
+ />
+ <ConfirmDialog
+ isOpen={pendingTemplateSource != null}
+ title="Load template"
+ message="Loading this template will replace the current contents of the code editor. Any changes you've made there will be lost. Do you want to continue?"
+ onCancel={() => setPendingTemplateSource(null)}
+ onConfirm={() => {
+ if (pendingTemplateSource != null) {
+ setCode(stripCodeExampleCopyrightHeader(pendingTemplateSource));
+ requestAnimationFrame(() => editorRef.current?.focus());
+ }
+ setPendingTemplateSource(null);
+ }}
+ />
</XDSHStack>
);
}
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index 1beeb35160..9aeb835e65 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -627,11 +627,14 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
// Open in Playground destination: the main /playground seeded with
// the theme-showcase template in the code editor (#code) and the
- // selected theme in the theme editor (?theme=<slug>). The button's
- // href does a plain full-page navigation, which the playground needs
- // to read the seeded code from window.location.hash reliably at
- // mount (App Router soft navigation doesn't reliably commit the hash
- // before that read, so the code could fall back to DEFAULT_CODE).
+ // selected theme in the theme editor (?theme=<slug>). Navigation goes
+ // through the framework — XDSButton's href renders the docsite's Next
+ // <Link> (via XDSLinkProvider), so this is a soft, client-side
+ // transition rather than a full-page reload. The playground reads the
+ // seeded code from window.location.hash in a mount effect (the
+ // App-Router-safe way to read a fragment — useSearchParams only sees
+ // the query string), which runs after the navigation has committed the
+ // new URL, so the hash is reliably present when it's read.
const customizeHref = buildPlaygroundHref(
THEME_SHOWCASE_SOURCE,
packageNameToSlug(selectedPkgName),
diff --git a/packages/cli/templates/pages/theme-showcase/page.tsx b/packages/cli/templates/pages/theme-showcase/page.tsx
index 0fe8afb1b8..3170cd7ab1 100644
--- a/packages/cli/templates/pages/theme-showcase/page.tsx
+++ b/packages/cli/templates/pages/theme-showcase/page.tsx
@@ -414,7 +414,7 @@ function StorePreview({
</XDSVStack>
</XDSCenter>
- <XDSGrid columns={isMobile ? 1 : {minWidth: 200}} gap={4}>
+ <XDSGrid columns={isMobile ? 1 : {minWidth: 200, max: 3}} gap={4}>
{PRODUCTS.map((p, i) => (
<XDSCard key={p.name} padding={0} height="100%">
<XDSVStack gap={0} xstyle={styles.cardStack}>