Skip to content

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

TypeScript

feat(cli): add playground defaults to 19 more components (#2047)

Cindy Zhangeb00e21d2bcb
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index a12dadc661..b766ea7695 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -158,7 +158,10 @@ function formatValue(value: unknown): string {
function generateCode(name: string, state: Record<string, unknown>): string {
const componentName = `XDS${name}`;
- const entries = Object.entries(state).filter(([, v]) => v !== undefined);
+ // Filter out docs-only props that shouldn't appear in user code
+ const entries = Object.entries(state).filter(
+ ([k, v]) => v !== undefined && k !== 'isInline',
+ );
if (entries.length === 0) return `<${componentName} />`;
diff --git a/apps/docsite/src/components/component-detail/resolveElements.ts b/apps/docsite/src/components/component-detail/resolveElements.ts
index 435c1be49a..991cbe8e3f 100644
--- a/apps/docsite/src/components/component-detail/resolveElements.ts
+++ b/apps/docsite/src/components/component-detail/resolveElements.ts
@@ -29,6 +29,16 @@ export function resolveElementDescriptor(
const Comp = getXDSComponent(desc.__element.replace(/^XDS/, ''));
const tag = Comp ?? desc.__element;
+ // Resolve any nested ElementDescriptors inside props
+ const resolvedProps: Record<string, unknown> = {};
+ if (desc.props) {
+ for (const [key, val] of Object.entries(desc.props)) {
+ resolvedProps[key] = isElementDescriptor(val)
+ ? resolveElementDescriptor(val)
+ : val;
+ }
+ }
+
let children: React.ReactNode = undefined;
if (desc.children != null) {
if (typeof desc.children === 'string') {
@@ -44,7 +54,7 @@ export function resolveElementDescriptor(
}
}
- return createElement(tag, desc.props ?? {}, children);
+ return createElement(tag, resolvedProps, children);
}
export function resolveValue(v: unknown): unknown {
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index 7a23a60568..5fcfc8de8c 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -23,6 +23,16 @@ export const docs = {
{guidance: false, description: 'Use AlertDialog for non-destructive actions — use a standard Dialog instead.'},
],
},
+ playground: {
+ defaults: {
+ isOpen: true,
+ isInline: true,
+ onOpenChange: undefined,
+ title: 'Delete item?',
+ description: 'This action cannot be undone. The item and all its data will be permanently removed.',
+ actionLabel: 'Delete',
+ },
+ },
components: [
{
name: 'XDSAlertDialog',
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index ba5dedb54d..3c95d48aa9 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -96,8 +96,7 @@ export const docs = {
contentPadding: 4,
topNav: {
__element: 'XDSTopNav',
- props: {label: 'Navigation'},
- children: {__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'My App'},
+ props: {label: 'Navigation', heading: {__element: 'XDSTopNavHeading', props: {heading: 'My App'}}},
},
sideNav: {
__element: 'XDSSideNav',
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
index 9ad8b89f17..339d278dc9 100644
--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -33,6 +33,12 @@ export const docs = {
'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
},
],
+ playground: {
+ defaults: {
+ ratio: 16 / 9,
+ children: {__element: 'XDSCenter', props: {height: '100%'}, children: {__element: 'XDSText', props: {color: 'secondary'}, children: '16:9'}},
+ },
+ },
theming: {
targets: [
{className: 'xds-aspect-ratio'},
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 29533ae2ae..a2579cc889 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -91,6 +91,13 @@ export const docs = {
},
],
+ playground: {
+ defaults: {
+ title: 'System maintenance scheduled',
+ description: 'The platform will be briefly unavailable on Sunday from 2–4 AM PST.',
+ status: 'info',
+ },
+ },
theming: {
targets: [
{className: 'xds-banner', visualProps: ['container', 'status']},
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 3e8a71a205..4669263ca7 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -33,6 +33,15 @@ export const docs = {
{name: 'style', type: 'CSSProperties', description: 'Inline styles for the root element. Prefer xstyle.'},
{name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
],
+ playground: {
+ defaults: {
+ children: [
+ {__element: 'XDSCard', props: {padding: 4}, children: 'Slide 1'},
+ {__element: 'XDSCard', props: {padding: 4}, children: 'Slide 2'},
+ {__element: 'XDSCard', props: {padding: 4}, children: 'Slide 3'},
+ ],
+ },
+ },
theming: {
targets: [
{className: 'xds-carousel'},
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
index 72ee320301..03175fccd5 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
@@ -42,6 +42,13 @@ export const docs = {
],
},
],
+ playground: {
+ defaults: {
+ code: "import {XDSButton} from '@xds/core/Button';\n\nexport function App() {\n return <XDSButton label=\"Hello\" variant=\"primary\" />;\n}",
+ language: 'tsx',
+ hasCopyButton: true,
+ },
+ },
theming: {
targets: [
{className: 'xds-code'},
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 258e0356ff..a1ef428c8d 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -4,6 +4,12 @@ export const docs = {
name: 'Collapsible',
group: 'Collapsible',
keywords: ["accordion","collapse","expandable","disclosure","toggle","panel","foldable","expander","expand"],
+ playground: {
+ defaults: {
+ trigger: 'Click to expand',
+ children: {__element: 'XDSText', props: {type: 'body'}, children: 'This content is revealed when the collapsible is expanded. It can contain any components.'},
+ },
+ },
theming: {
targets: [
{className: 'xds-collapsible'},
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index d8a645a15f..13310e719b 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -4,6 +4,20 @@ export const docs = {
name: 'Dialog',
group: 'Dialog',
keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],
+ playground: {
+ defaults: {
+ isOpen: true,
+ isInline: true,
+ onOpenChange: undefined,
+ width: 400,
+ children: {
+ __element: 'XDSVStack', props: {gap: 2}, children: [
+ {__element: 'XDSHeading', props: {level: 3}, children: 'Dialog Title'},
+ {__element: 'XDSText', props: {type: 'body'}, children: 'Are you sure you want to proceed? This action can be undone later from settings.'},
+ ],
+ },
+ },
+ },
theming: {
container: true,
targets: [
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index fabd1a5983..d56f2c6547 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -4,6 +4,12 @@ export const docs = {
name: 'Field',
group: 'Field',
keywords: ["field","formfield","formgroup","formcontrol","label","input","required","optional","helpertext","hint"],
+ playground: {
+ defaults: {
+ label: 'Email address',
+ children: {__element: 'XDSTextInput', props: {label: 'Email', placeholder: '[email protected]'}},
+ },
+ },
theming: {
targets: [
{className: 'xds-field'},
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index c9c5b65339..6c54515e95 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -2,7 +2,14 @@
export const docs = {
name: 'HoverCard',
+ group: 'HoverCard',
keywords: ["hovercard","hover card","popover","tooltip","preview card","flyout","overlay","hover popup"],
+ playground: {
+ defaults: {
+ content: {__element: 'XDSText', props: {type: 'body'}, children: 'Additional details shown on hover.'},
+ children: {__element: 'XDSLink', props: {href: '#'}, children: 'Hover for details'},
+ },
+ },
theming: {
targets: [
{className: 'xds-hovercard'},
diff --git a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
index 56ae4a67b4..07e83525e2 100644
--- a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
@@ -1,6 +1,7 @@
/** @type {import('../docs-types').HookDoc} */
export const docs = {
name: 'useXDSHoverCard',
+ group: 'HoverCard',
keywords: ['hovercard', 'hover', 'preview', 'card', 'tooltip', 'popup', 'floating', 'anchor'],
params: [
{
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 84a849e501..6a0b57ad97 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -4,6 +4,13 @@ export const docs = {
name: 'Layout',
group: 'Layout',
keywords: ["layout","container","content","flex","box","wrapper","scaffold","page","shell"],
+ playground: {
+ defaults: {
+ header: {__element: 'XDSLayoutHeader', props: {}, children: {__element: 'XDSHeading', props: {level: 3}, children: 'Page Title'}},
+ content: {__element: 'XDSLayoutContent', props: {}, children: {__element: 'XDSText', props: {type: 'body', color: 'secondary'}, children: 'Main content area. This is the scrollable center section of the layout.'}},
+ footer: {__element: 'XDSLayoutFooter', props: {}, children: {__element: 'XDSText', props: {type: 'supporting', color: 'secondary'}, children: 'Footer — status bar or actions'}},
+ },
+ },
theming: {
targets: [
{className: 'xds-layout', visualProps: ['height']},
@@ -23,31 +30,31 @@ export const docs = {
name: 'content',
type: 'ReactNode',
description: 'Main content area (center).',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Content text'}],
+ slotElements: [{__element: 'XDSLayoutContent', props: {}, children: 'Content'}],
},
{
name: 'header',
type: 'ReactNode',
description: 'Header slot.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
+ slotElements: [{__element: 'XDSLayoutHeader', props: {}, children: 'Header'}],
},
{
name: 'footer',
type: 'ReactNode',
description: 'Footer slot.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
+ slotElements: [{__element: 'XDSLayoutFooter', props: {}, children: 'Footer'}],
},
{
name: 'start',
type: 'ReactNode',
description: 'Start panel (left in LTR).',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Panel content'}],
+ slotElements: [{__element: 'XDSLayoutPanel', props: {}, children: 'Panel'}],
},
{
name: 'end',
type: 'ReactNode',
description: 'End panel (right in LTR).',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Panel content'}],
+ slotElements: [{__element: 'XDSLayoutPanel', props: {}, children: 'Panel'}],
},
{
name: 'height',
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 283af9d0e0..8469ec778a 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -3,6 +3,12 @@
export const docs = {
name: 'Link',
keywords: ["link","anchor","href","hyperlink","navigation","url","external","textlink"],
+ playground: {
+ defaults: {
+ href: '#',
+ children: 'Learn more',
+ },
+ },
theming: {
targets: [
{className: 'xds-link', visualProps: ['color']},
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index d6046fb466..08755f6c36 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -96,6 +96,11 @@ export const docs = {
description: 'Test selector for automated testing frameworks.',
},
],
+ playground: {
+ defaults: {
+ children: '## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @xds/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {XDSButton} from \'@xds/core/Button\';\n```\n\n**Bold**, *italic*, and `inline code` all work.',
+ },
+ },
theming: {
targets: [
{className: 'xds-markdown', visualProps: ['density']},
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index c2f2ba94e8..a7f2c4a74e 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -62,6 +62,15 @@ export const docs = {
'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
},
],
+ playground: {
+ defaults: {
+ items: [
+ {label: 'Edit', value: 'edit'},
+ {label: 'Duplicate', value: 'duplicate'},
+ {label: 'Delete', value: 'delete'},
+ ],
+ },
+ },
theming: {
targets: [
{className: 'xds-more-menu'},
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 588f56b220..4bef89046b 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Popover',
+ group: 'Popover',
keywords: ["popover","popup","dropdown","tooltip","overlay","flyout","callout","popper","anchor","floating","bubble"],
components: [
{
@@ -92,6 +93,12 @@ export const docs = {
],
},
],
+ playground: {
+ defaults: {
+ content: {__element: 'XDSText', props: {type: 'body'}, children: 'Popover content goes here.'},
+ children: {__element: 'XDSButton', props: {label: 'Open popover', variant: 'secondary'}},
+ },
+ },
theming: {
targets: [
{className: 'xds-popover'},
diff --git a/packages/core/src/Popover/useXDSPopover.doc.mjs b/packages/core/src/Popover/useXDSPopover.doc.mjs
index ffa14117e8..4c605fe3bc 100644
--- a/packages/core/src/Popover/useXDSPopover.doc.mjs
+++ b/packages/core/src/Popover/useXDSPopover.doc.mjs
@@ -1,6 +1,7 @@
/** @type {import('../docs-types').HookDoc} */
export const docs = {
name: 'useXDSPopover',
+ group: 'Popover',
keywords: ['popover', 'popup', 'dropdown', 'floating', 'anchor', 'dialog', 'overlay', 'flyout'],
params: [
{
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 3e74c26148..de66ffa653 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -4,6 +4,15 @@ export const docs = {
name: 'SideNav',
group: 'SideNav',
keywords: ["sidenav","sidebar","navigation","drawer","menu","nav","aside","sidemenu","navmenu","sider","treeview"],
+ playground: {
+ defaults: {
+ children: [
+ {__element: 'XDSSideNavItem', props: {label: 'Dashboard', isSelected: true}},
+ {__element: 'XDSSideNavItem', props: {label: 'Projects'}},
+ {__element: 'XDSSideNavItem', props: {label: 'Settings'}},
+ ],
+ },
+ },
theming: {
targets: [
{className: 'xds-side-nav', visualProps: ['mode']},
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 7f8e874853..1c6782445f 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -4,6 +4,20 @@ export const docs = {
name: 'Table',
group: 'Table',
keywords: ["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],
+ playground: {
+ defaults: {
+ data: [
+ {name: 'Alice Chen', role: 'Engineer', status: 'Active'},
+ {name: 'Bob Smith', role: 'Designer', status: 'Active'},
+ {name: 'Carol Wu', role: 'PM', status: 'Away'},
+ ],
+ columns: [
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role'},
+ {key: 'status', header: 'Status'},
+ ],
+ },
+ },
theming: {
targets: [
{className: 'xds-base-table'},
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 9daf77ab97..4973d66216 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -3,6 +3,12 @@
export const docs = {
name: 'Text',
keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"],
+ playground: {
+ defaults: {
+ children: 'The quick brown fox jumps over the lazy dog.',
+ type: 'body',
+ },
+ },
theming: {
targets: [
{className: 'xds-heading', visualProps: ['level', 'color']},
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index 6e7afda346..c71edb673d 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -2,6 +2,13 @@
export const docs = {
name: 'Tooltip',
+ group: 'Tooltip',
+ playground: {
+ defaults: {
+ content: 'Helpful tooltip text',
+ children: {__element: 'XDSButton', props: {label: 'Hover me', variant: 'secondary'}},
+ },
+ },
keywords: ["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],
components: [
{
diff --git a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
index c361a74214..d968595f2b 100644
--- a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
+++ b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
@@ -1,6 +1,7 @@
/** @type {import('../docs-types').HookDoc} */
export const docs = {
name: 'useXDSTooltip',
+ group: 'Tooltip',
keywords: ['tooltip', 'hint', 'label', 'hover', 'info', 'title', 'floating'],
params: [
{
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index 59eb6972c5..7b20d10b3b 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -4,6 +4,12 @@ export const docs = {
name: 'TopNav',
group: 'TopNav',
keywords: ["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],
+ playground: {
+ defaults: {
+ label: 'Navigation',
+ heading: {__element: 'XDSTopNavHeading', props: {heading: 'My App'}},
+ },
+ },
theming: {
targets: [
{className: 'xds-top-nav', states: ['mode']},