Skip to content

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

TypeScript

refactor(docsite): wire slotElements through playground UI (#2012)

Cindy Zhange94facef658d
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index 361ac47bff..a12dadc661 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -5,12 +5,11 @@ import {
useMemo,
useState,
useCallback,
- type ComponentType,
isValidElement,
Component,
type ReactNode,
} from 'react';
-import * as XDSCore from '@xds/core';
+import {getXDSComponent, resolveValue} from './resolveElements';
import {XDSButton} from '@xds/core/Button';
import {XDSCard} from '@xds/core/Card';
import {XDSCenter} from '@xds/core/Center';
@@ -26,49 +25,8 @@ import {
import type {
PropDoc,
PlaygroundConfig,
- ElementDescriptor,
} from '../../generated/componentRegistry';
-function isElementDescriptor(v: unknown): v is ElementDescriptor {
- return v != null && typeof v === 'object' && '__element' in v;
-}
-
-function resolveElementDescriptor(desc: ElementDescriptor): React.ReactNode {
- const Comp = getXDSComponent(desc.__element.replace(/^XDS/, ''));
- const tag = Comp ?? desc.__element;
-
- let children: React.ReactNode = undefined;
- if (desc.children != null) {
- if (typeof desc.children === 'string') {
- children = desc.children;
- } else if (Array.isArray(desc.children)) {
- children = desc.children.map((c, i) =>
- typeof c === 'string'
- ? c
- : createElement('span', {key: i}, resolveElementDescriptor(c)),
- );
- } else {
- children = resolveElementDescriptor(desc.children);
- }
- }
-
- return createElement(tag, desc.props ?? {}, children);
-}
-
-function resolveValue(v: unknown): unknown {
- if (isElementDescriptor(v)) return resolveElementDescriptor(v);
- return v;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyXDSComponent = ComponentType<any>;
-
-function getXDSComponent(name: string): AnyXDSComponent | null {
- const key = `XDS${name}` as keyof typeof XDSCore;
- const value = XDSCore[key];
- return typeof value === 'function' ? (value as AnyXDSComponent) : null;
-}
-
export interface KnobProp {
row: PropDoc;
control: PropControlDescriptor;
@@ -130,6 +88,26 @@ function buildInitialState(
const def = coerceDefault(row.default, control);
if (def !== undefined) {
state[row.name] = def;
+ } else if (control.kind === 'slot-list') {
+ // Always generate initial items for slot-lists (empty list isn't useful)
+ const slotEl = row.slotElements?.[0];
+ if (slotEl) {
+ state[row.name] = [1, 2, 3].map(n => {
+ const tweaked = {...slotEl};
+ const props = {...(tweaked.props ?? {})};
+ if (typeof props.label === 'string') {
+ props.label = `${props.label} ${n}`;
+ }
+ if (typeof props.value === 'string') {
+ props.value = `${props.value}-${n}`;
+ }
+ tweaked.props = props;
+ if (typeof tweaked.children === 'string') {
+ tweaked.children = `${tweaked.children} ${n}`;
+ }
+ return resolveValue(tweaked);
+ });
+ }
} else if (row.required) {
switch (control.kind) {
case 'enum':
diff --git a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
index a342d7e953..53f1374b44 100644
--- a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
+++ b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
@@ -10,10 +10,12 @@ import {XDSNumberInput} from '@xds/core/NumberInput';
import {XDSSelector} from '@xds/core/Selector';
import {XDSIcon} from '@xds/core/Icon';
import {XDSBadge} from '@xds/core/Badge';
-import * as XDSCore from '@xds/core';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {MinusIcon, PlusIcon} from '@heroicons/react/24/outline';
import {useMediaQuery} from '@xds/core/hooks';
import type {PropControlDescriptor} from './parsePropType';
import type {KnobProp} from './InteractivePreview';
+import {resolveElementDescriptor} from './resolveElements';
import type {PropDoc} from '../../generated/componentRegistry';
function formatType(type: string, defaultValue?: string): React.ReactNode {
@@ -49,19 +51,21 @@ function formatType(type: string, defaultValue?: string): React.ReactNode {
function resolveSlotElement(
componentName: string,
- slotElements?: Array<{__element: string; props?: Record<string, unknown>}>,
+ slotElements?: Array<{
+ __element: string;
+ props?: Record<string, unknown>;
+ children?: unknown;
+ }>,
): React.ReactNode {
- // If we have slotElements metadata, use the matching one
if (slotElements) {
const match = slotElements.find(el => el.__element === componentName);
if (match) {
- const key = match.__element.replace(/^XDS/, '') as keyof typeof XDSCore;
- const Comp = typeof XDSCore[key] === 'function' ? XDSCore[key] : null;
- if (Comp)
- return createElement(Comp as React.ComponentType, match.props ?? {});
+ return resolveElementDescriptor(
+ match as import('../../generated/componentRegistry').ElementDescriptor,
+ );
}
}
- // Fallback to hardcoded defaults
+ // Fallback for common components without slotElements declared
switch (componentName) {
case 'XDSIcon':
return createElement(XDSIcon, {icon: 'check', size: 'sm'});
@@ -122,6 +126,71 @@ function ElementControl({
);
}
+function SlotListControl({
+ control,
+ value,
+ onChange,
+ prop,
+}: {
+ control: Extract<PropControlDescriptor, {kind: 'slot-list'}>;
+ value: unknown;
+ onChange: (next: unknown) => void;
+ prop: PropDoc;
+}) {
+ const items = Array.isArray(value) ? value : [];
+ const count = items.length;
+
+ const addItem = () => {
+ const slotEl = prop.slotElements?.[0];
+ if (!slotEl) return;
+ const n = count + 1;
+ const tweaked = {...slotEl};
+ const props = {...(tweaked.props ?? {})};
+ if (typeof props.label === 'string') props.label = `${props.label} ${n}`;
+ if (typeof props.value === 'string') props.value = `${props.value}-${n}`;
+ tweaked.props = props;
+ const children =
+ typeof tweaked.children === 'string'
+ ? `${tweaked.children} ${n}`
+ : tweaked.children;
+ const newEl = resolveElementDescriptor({
+ ...tweaked,
+ children,
+ } as import('../../generated/componentRegistry').ElementDescriptor);
+ onChange([...items, newEl]);
+ };
+
+ const removeItem = () => {
+ if (count > 0) onChange(items.slice(0, -1));
+ };
+
+ return (
+ <XDSHStack gap={2} vAlign="center">
+ <XDSText type="supporting" color="secondary">
+ {count} {control.options[0].label}
+ {count !== 1 ? 's' : ''}
+ </XDSText>
+ <XDSHStack gap={1}>
+ <XDSIconButton
+ label="Remove item"
+ icon={<MinusIcon width={16} height={16} />}
+ variant="ghost"
+ size="sm"
+ isDisabled={count === 0}
+ onClick={removeItem}
+ />
+ <XDSIconButton
+ label="Add item"
+ icon={<PlusIcon width={16} height={16} />}
+ variant="ghost"
+ size="sm"
+ onClick={addItem}
+ />
+ </XDSHStack>
+ </XDSHStack>
+ );
+}
+
function InlineControl({
control,
value,
@@ -179,6 +248,15 @@ function InlineControl({
prop={prop}
/>
);
+ case 'slot-list':
+ return (
+ <SlotListControl
+ control={control}
+ value={value}
+ onChange={onChange}
+ prop={prop}
+ />
+ );
default:
return null;
}
diff --git a/apps/docsite/src/components/component-detail/parsePropType.ts b/apps/docsite/src/components/component-detail/parsePropType.ts
index 1eaa9315d9..9bbef7023c 100644
--- a/apps/docsite/src/components/component-detail/parsePropType.ts
+++ b/apps/docsite/src/components/component-detail/parsePropType.ts
@@ -17,6 +17,7 @@ export type PropControlDescriptor =
| {kind: 'number'}
| {kind: 'callback'}
| {kind: 'element'; options: ElementOption[]}
+ | {kind: 'slot-list'; options: ElementOption[]}
| {kind: 'unknown'};
const STRING_LITERAL_RE = /^['"]([^'"]*)['"]$/;
@@ -66,13 +67,15 @@ export function parsePropType(
// If slotElements is declared, use it directly for the element control
if (slotElements && slotElements.length > 0) {
- return {
- kind: 'element',
- options: slotElements.map(el => ({
- label: el.__element.replace(/^XDS/, ''),
- componentName: el.__element,
- })),
- };
+ const options = slotElements.map(el => ({
+ label: el.__element.replace(/^XDS/, ''),
+ componentName: el.__element,
+ }));
+ // children with slotElements → repeatable slot list (add/remove items)
+ if (propName === 'children') {
+ return {kind: 'slot-list', options};
+ }
+ return {kind: 'element', options};
}
if (CALLBACK_RE.test(t)) return {kind: 'callback'};
diff --git a/apps/docsite/src/components/component-detail/resolveElements.ts b/apps/docsite/src/components/component-detail/resolveElements.ts
new file mode 100644
index 0000000000..435c1be49a
--- /dev/null
+++ b/apps/docsite/src/components/component-detail/resolveElements.ts
@@ -0,0 +1,53 @@
+/**
+ * Resolves ElementDescriptor objects into React elements at runtime.
+ * Shared between InteractivePreview (for playground defaults) and
+ * PlaygroundPropsTable (for slot element controls).
+ */
+
+import {createElement, type ComponentType} from 'react';
+import * as XDSCore from '@xds/core';
+import type {ElementDescriptor} from '../../generated/componentRegistry';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyComponent = ComponentType<any>;
+
+export function getXDSComponent(name: string): AnyComponent | null {
+ // Try both with and without XDS prefix
+ const withPrefix = `XDS${name}` as keyof typeof XDSCore;
+ const direct = name as keyof typeof XDSCore;
+ const value = XDSCore[withPrefix] ?? XDSCore[direct];
+ return typeof value === 'function' ? (value as AnyComponent) : null;
+}
+
+export function isElementDescriptor(v: unknown): v is ElementDescriptor {
+ return v != null && typeof v === 'object' && '__element' in v;
+}
+
+export function resolveElementDescriptor(
+ desc: ElementDescriptor,
+): React.ReactNode {
+ const Comp = getXDSComponent(desc.__element.replace(/^XDS/, ''));
+ const tag = Comp ?? desc.__element;
+
+ let children: React.ReactNode = undefined;
+ if (desc.children != null) {
+ if (typeof desc.children === 'string') {
+ children = desc.children;
+ } else if (Array.isArray(desc.children)) {
+ children = desc.children.map((c, i) =>
+ typeof c === 'string'
+ ? c
+ : createElement('span', {key: i}, resolveElementDescriptor(c)),
+ );
+ } else {
+ children = resolveElementDescriptor(desc.children);
+ }
+ }
+
+ return createElement(tag, desc.props ?? {}, children);
+}
+
+export function resolveValue(v: unknown): unknown {
+ if (isElementDescriptor(v)) return resolveElementDescriptor(v);
+ return v;
+}
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index 747c0cb19c..11d34fad0b 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -30,23 +30,27 @@ export const docs = {
name: 'topNav',
type: 'ReactNode',
description: 'Top navigation slot, typically XDSTopNav.',
+ slotElements: [{__element: 'XDSTopNav', props: {label: 'Navigation'}}],
},
{
name: 'sideNav',
type: 'ReactNode',
description: 'Side navigation slot, typically XDSSideNav.',
+ slotElements: [{__element: 'XDSSideNav', props: {}}],
},
{
name: 'mobileNav',
type: 'ReactNode',
description:
'Mobile navigation configuration. Accepts false (disable), config object (tune auto behavior), or ReactNode (full custom drawer).',
+ slotElements: [{__element: 'XDSMobileNav', props: {}}],
},
{
name: 'banner',
type: 'ReactNode',
description:
'Banner slot for system-wide announcements, placed above the topNav.',
+ slotElements: [{__element: 'XDSBanner', props: {title: 'Info', status: 'info'}}],
},
{
name: 'height',
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index d5dd75f20f..c5aaccb331 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -63,6 +63,7 @@ export const docs = {
name: 'status',
type: 'ReactNode',
description: 'Corner content for status indicators.',
+ slotElements: [{__element: 'XDSStatusDot', props: {variant: 'online'}}],
},
], },
{
@@ -85,6 +86,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Icon centered inside the dot (hidden at tiny sizes).',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
],
},
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index 3fc837f358..e911bced49 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -20,6 +20,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Optional leading icon.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
],
playground: {
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 381ccb840f..29533ae2ae 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -46,6 +46,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Override the default status icon.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'isDismissable',
@@ -64,6 +65,10 @@ export const docs = {
type: 'ReactNode',
description:
'Action content rendered in the header area, end-aligned. Typically a button or link.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'container',
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index 54218f32b2..4ea8dd4b25 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -40,6 +40,7 @@ export const docs = {
type: 'ReactNode',
description:
'XDSBreadcrumbItem elements to render inside the breadcrumb trail.',
+ slotElements: [{__element: 'XDSBreadcrumbItem', props: {href: '#'}, children: 'Page'}],
required: true,
},
{
@@ -47,6 +48,7 @@ export const docs = {
type: 'ReactNode',
description: 'Separator rendered between breadcrumb items.',
default: "'/'",
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'chevronRight', size: 'sm'}}],
},
{
name: 'variant',
@@ -101,6 +103,7 @@ export const docs = {
name: 'startIcon',
type: 'ReactNode',
description: 'Icon rendered before the item label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'as',
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index c97b10ca0d..e1eeb3c50e 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -36,7 +36,9 @@ export const docs = {
description: 'Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn\'t full.',
props: [
{name: 'children', type: 'ReactNode', description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.', required: true},
- {name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.'},
+ {name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.',
+ slotElements: [{__element: 'XDSEmptyState', props: {title: 'No items', description: 'Nothing to show.'}}],
+ },
{name: 'scrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.'},
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},
],
@@ -47,9 +49,13 @@ export const docs = {
props: [
{name: 'sender', type: "'user' | 'assistant' | 'system'", description: 'Who sent this message — controls alignment and layout.', required: true},
{name: 'children', type: 'ReactNode', description: 'Free-form content: bubbles, asset lists, tool calls, images.', required: true},
- {name: 'avatar', type: 'ReactNode', description: 'Avatar element rendered beside the message. Typically XDSAvatar.'},
+ {name: 'avatar', type: 'ReactNode', description: 'Avatar element rendered beside the message. Typically XDSAvatar.',
+ slotElements: [{__element: 'XDSAvatar', props: {name: 'User', size: 'sm'}}],
+ },
{name: 'name', type: 'ReactNode', description: 'Sender name rendered above the message body. Use when the first child is raw content (not a bubble). If the first child is a bubble, put the name on the bubble\'s `name` prop instead.'},
- {name: 'metadata', type: 'ReactNode', description: 'Metadata rendered below the message body. Use when the last child is raw content (not a bubble). If the last child is a bubble, put metadata on the bubble\'s `metadata` prop instead.'},
+ {name: 'metadata', type: 'ReactNode', description: 'Metadata rendered below the message body. Use when the last child is raw content (not a bubble). If the last child is a bubble, put metadata on the bubble\'s `metadata` prop instead.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Metadata'}],
+ },
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density. Inherited from list context if not set.'},
],
},
@@ -60,7 +66,9 @@ export const docs = {
{name: 'children', type: 'ReactNode', description: 'Bubble content — text, XDSMarkdown, or any ReactNode.', required: true},
{name: 'variant', type: "'filled' | 'ghost'", description: "Visual variant. 'filled' renders sender-colored background (default). 'ghost' renders transparent background but keeps padding for alignment.", default: "'filled'"},
{name: 'name', type: 'ReactNode', description: "Sender name rendered above the bubble, aligned with bubble text padding. Use on the first bubble in a message. If the first content is raw (no bubble), use XDSChatMessage's `name` prop instead."},
- {name: 'metadata', type: 'ReactNode', description: "Metadata content rendered below the bubble, aligned with bubble text padding. Use on the last bubble in a message. If the last content is raw (no bubble), use XDSChatMessage's `metadata` prop instead."},
+ {name: 'metadata', type: 'ReactNode', description: "Metadata content rendered below the bubble, aligned with bubble text padding. Use on the last bubble in a message. If the last content is raw (no bubble), use XDSChatMessage's `metadata` prop instead.",
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Metadata'}],
+ },
{name: 'group', type: "'first' | 'middle' | 'last'", description: 'Position within a multi-bubble group. Controls corner radius reduction on the sender side. Leave unset for standalone bubbles (full radius).'},
],
},
@@ -68,8 +76,12 @@ export const docs = {
name: 'XDSChatMessageMetadata',
description: 'Composable metadata row for chat messages. Renders timestamp, footer content, and delivery status in a single row. Direction reverses for user sender. Renders nothing if all props are empty.',
props: [
- {name: 'timestamp', type: 'ReactNode', description: 'Timestamp content — a string or XDSTimestamp component.'},
- {name: 'footer', type: 'ReactNode', description: 'Footer content — model info, reaction buttons, copy button.'},
+ {name: 'timestamp', type: 'ReactNode', description: 'Timestamp content — a string or XDSTimestamp component.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Just now'}],
+ },
+ {name: 'footer', type: 'ReactNode', description: 'Footer content — model info, reaction buttons, copy button.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
+ },
{name: 'status', type: "'sending' | 'sent' | 'delivered' | 'read' | 'error'", description: 'Message delivery status. Shows icon + label.'},
],
},
@@ -79,7 +91,9 @@ export const docs = {
props: [
{name: 'children', type: 'ReactNode', description: 'System message content — a short, factual string like a date, a join/leave notice, or a status change.', required: true},
{name: 'variant', type: "'default' | 'divider'", description: "Visual variant. 'default' renders centered text. 'divider' adds horizontal lines on each side via XDSDivider — use for date separators and section breaks.", default: "'default'"},
- {name: 'icon', type: 'ReactNode', description: 'Leading icon that reinforces the message type. Wrap in XDSIcon for consistent sizing. Use for membership changes, encryption notices, or AI activity.'},
+ {name: 'icon', type: 'ReactNode', description: 'Leading icon that reinforces the message type. Wrap in XDSIcon for consistent sizing. Use for membership changes, encryption notices, or AI activity.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
],
},
{
@@ -94,13 +108,27 @@ export const docs = {
{name: 'placeholder', type: 'string', description: 'Placeholder text shown when the input is empty.', default: "'Type a message\u2026'"},
{name: 'isDisabled', type: 'boolean', description: 'Disables the composer.', default: 'false'},
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density.', default: "'balanced'"},
- {name: 'drawer', type: 'ReactNode', description: 'Slot: collapsible drawer above the input — attachments, context chips, etc. Use XDSChatComposerDrawer.'},
- {name: 'headerActions', type: 'ReactNode', description: 'Slot: left-aligned header actions (attach, mention buttons). Use icon-only size="sm" buttons.'},
- {name: 'headerContext', type: 'ReactNode', description: 'Slot: right-aligned contextual info in the header (context window usage, XDSProgressBar, supporting text).'},
- {name: 'input', type: 'ReactNode', description: 'Slot: custom input element. Replaces the default textarea. Use XDSChatComposerInput for trigger menus.'},
- {name: 'footerActions', type: 'ReactNode', description: 'Slot: left-aligned footer actions (model selector, etc).'},
- {name: 'sendActions', type: 'ReactNode', description: 'Slot: actions to the left of the send button.'},
- {name: 'sendButton', type: 'ReactNode', description: 'Slot: custom send button. Replaces the default send/stop button.'},
+ {name: 'drawer', type: 'ReactNode', description: 'Slot: collapsible drawer above the input — attachments, context chips, etc. Use XDSChatComposerDrawer.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Drawer content'}],
+ },
+ {name: 'headerActions', type: 'ReactNode', description: 'Slot: left-aligned header actions (attach, mention buttons). Use icon-only size="sm" buttons.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
+ },
+ {name: 'headerContext', type: 'ReactNode', description: 'Slot: right-aligned contextual info in the header (context window usage, XDSProgressBar, supporting text).',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Context'}],
+ },
+ {name: 'input', type: 'ReactNode', description: 'Slot: custom input element. Replaces the default textarea. Use XDSChatComposerInput for trigger menus.',
+ slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
+ },
+ {name: 'footerActions', type: 'ReactNode', description: 'Slot: left-aligned footer actions (model selector, etc).',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
+ },
+ {name: 'sendActions', type: 'ReactNode', description: 'Slot: actions to the left of the send button.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
+ },
+ {name: 'sendButton', type: 'ReactNode', description: 'Slot: custom send button. Replaces the default send/stop button.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
+ },
{name: 'status', type: "{ type: 'error' | 'warning'; message?: string }", description: 'Status message rendered below (or above) the composer.'},
{name: 'statusPosition', type: "'top' | 'bottom'", description: 'Where to render the status.', default: "'bottom'"},
],
@@ -144,8 +172,12 @@ export const docs = {
{name: 'isDisabled', type: 'boolean', description: 'Whether the send button is disabled. Defaults to !canSend from context.'},
{name: 'onSend', type: '() => void', description: 'Called when the user clicks send. Defaults to context onSubmit.'},
{name: 'onStop', type: '() => void', description: 'Called when the user clicks stop during streaming. Defaults to context onStop.'},
- {name: 'sendIcon', type: 'ReactNode', description: 'Custom icon for the send state. Defaults to arrowUp from icon registry.'},
- {name: 'stopIcon', type: 'ReactNode', description: 'Custom icon for the stop state. Defaults to stop from icon registry.'},
+ {name: 'sendIcon', type: 'ReactNode', description: 'Custom icon for the send state. Defaults to arrowUp from icon registry.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
+ {name: 'stopIcon', type: 'ReactNode', description: 'Custom icon for the stop state. Defaults to stop from icon registry.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
{name: 'size', type: "'sm' | 'md'", description: 'Button size.', default: "'md'"},
{name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.'},
],
@@ -214,8 +246,12 @@ const chatLayoutComponent = {
description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Adapts density (compact/balanced/spacious) automatically via container width observation. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
props: [
{name: 'children', type: 'ReactNode', description: 'Message content — typically XDSChatMessageList. Flows naturally in the page and scrolls with the container.', required: true},
- {name: 'composer', type: 'ReactNode', description: 'Composer element — typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.', required: true},
- {name: 'emptyState', type: 'ReactNode', description: 'Content shown when children is empty. Centered vertically in the message area.'},
+ {name: 'composer', type: 'ReactNode', description: 'Composer element — typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.', required: true,
+ slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
+ },
+ {name: 'emptyState', type: 'ReactNode', description: 'Content shown when children is empty. Centered vertically in the message area.',
+ slotElements: [{__element: 'XDSEmptyState', props: {title: 'No items', description: 'Nothing to show.'}}],
+ },
{name: 'scrollButton', type: 'ReactNode | null', description: 'Scroll-to-bottom button rendered above the composer. Defaults to XDSChatLayoutScrollButton with auto-scroll integration. Pass null to hide.'},
{name: 'scrollRef', type: 'React.RefObject<HTMLElement | null>', description: 'External scroll container ref. When provided, auto-scroll and scroll-to-bottom target this element instead of the layout root. Use when the chat is embedded in a page where a parent element or the document body scrolls.'},
],
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index b8f659e257..c7161dd62c 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -20,6 +20,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'XDSCheckboxListItem elements.',
+ slotElements: [{__element: 'XDSCheckboxListItem', props: {label: 'Option', value: 'option'}}],
required: true,
},
{
@@ -110,6 +111,10 @@ export const docs = {
name: 'endContent',
type: 'ReactNode',
description: 'Content rendered after the label area.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'isDisabled',
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index ece891875f..258e0356ff 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -20,6 +20,7 @@ export const docs = {
type: 'ReactNode',
description: 'Content shown in the trigger area (always visible).',
required: true,
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Trigger'}],
},
{
name: 'children',
@@ -81,6 +82,7 @@ export const docs = {
type: 'ReactNode',
description: 'XDSCollapsible instances to coordinate.',
required: true,
+ slotElements: [{__element: 'XDSCollapsible', props: {trigger: 'Section'}, children: 'Content'}],
},
],
},
diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
index e993333b6e..f430dd442f 100644
--- a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
@@ -46,6 +46,7 @@ export const docs = {
description:
'Input slot. Defaults to XDSCommandPaletteInput with standard behavior.',
default: '<XDSCommandPaletteInput />',
+ slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
},
{
name: 'footer',
@@ -53,6 +54,7 @@ export const docs = {
description:
'Footer slot. Defaults to XDSCommandPaletteFooter showing keyboard hints.',
default: '<XDSCommandPaletteFooter />',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
},
{
name: 'renderItem',
@@ -131,6 +133,10 @@ export const docs = {
type: 'ReactNode',
description:
'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'value',
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index efd967e481..d8a645a15f 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -106,12 +106,17 @@ export const docs = {
type: 'ReactNode',
description:
'Content before the title (e.g., a back button).',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'endContent',
type: 'ReactNode',
description:
'Content after the title, before close button.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'hasDivider',
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index d47ad90365..9d621757c1 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -22,12 +22,14 @@ export const docs = {
type: 'ReactNode',
description:
'Optional icon or illustration displayed above the title; rendered as decorative (aria-hidden="true").',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'actions',
type: 'ReactNode',
description:
'Optional action buttons displayed below the description, laid out horizontally by default and stacked vertically when isCompact is true.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'secondary'}}],
},
{
name: 'headingLevel',
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 1c7a154844..aaf17f44a2 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -29,6 +29,7 @@ export const docs = {
type: 'ReactNode',
description: 'Hover card content.',
required: true,
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Content text'}],
},
{
name: 'placement',
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index 3f81666e40..98a30888f3 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -18,6 +18,7 @@ export const docs = {
type: 'ReactNode',
description: 'Icon element rendered inside the button.',
required: true,
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'variant',
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 7cbab6878d..84a849e501 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -23,26 +23,31 @@ export const docs = {
name: 'content',
type: 'ReactNode',
description: 'Main content area (center).',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Content text'}],
},
{
name: 'header',
type: 'ReactNode',
description: 'Header slot.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
},
{
name: 'footer',
type: 'ReactNode',
description: 'Footer slot.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
},
{
name: 'start',
type: 'ReactNode',
description: 'Start panel (left in LTR).',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Panel content'}],
},
{
name: 'end',
type: 'ReactNode',
description: 'End panel (right in LTR).',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Panel content'}],
},
{
name: 'height',
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 5e0c59ad4c..030ea67fa6 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -18,6 +18,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'List items (XDSListItem components).',
+ slotElements: [{__element: 'XDSListItem', props: {label: 'List item'}}],
},
{
name: 'density',
@@ -36,6 +37,7 @@ export const docs = {
type: 'ReactNode',
description:
'Header content, associated with the list via aria-labelledby.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
},
{
name: 'listStyle',
@@ -74,12 +76,17 @@ export const docs = {
type: 'ReactNode',
description:
'Content rendered before the label area (e.g. icon, avatar).',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'endContent',
type: 'ReactNode',
description:
'Content rendered after the label area (e.g. badge, chevron).',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'onClick',
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 3a62e0d17b..df20e794c1 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -22,6 +22,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'Metadata items (XDSMetadataListItem components).',
+ slotElements: [{__element: 'XDSMetadataListItem', props: {label: 'Key'}, children: 'Value'}],
required: true,
},
{
@@ -83,6 +84,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Icon rendered before the label text.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
],
},
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index 59a6b7b858..c2f2ba94e8 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -35,6 +35,7 @@ export const docs = {
type: 'ReactNode',
description:
'Override the default three-dot icon. Accepts any ReactNode.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'isDisabled',
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
index abd8b67741..678a13347c 100644
--- a/packages/core/src/NavIcon/NavIcon.doc.mjs
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -11,6 +11,7 @@ export const docs = {
description:
'The icon element to render inside the circular background. Should be an XDSIcon or similar icon component.',
required: true,
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
],
theming: {
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index e48aeb6453..5ef5afde34 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -25,6 +25,7 @@ export const docs = {
type: 'ReactNode',
description: 'Content to display inside the popover.',
required: true,
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Content text'}],
},
{
name: 'placement',
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 5edb1864b1..14f962399e 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -101,6 +101,10 @@ export const docs = {
type: 'ReactNode',
description:
'Content to display at the end of the input row. Useful for action buttons or other controls.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'resultCount',
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 54a6116380..b2844874fc 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -40,6 +40,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'XDSRadioListItem elements.',
+ slotElements: [{__element: 'XDSRadioListItem', props: {label: 'Option', value: 'option'}}],
required: true,
},
{
@@ -134,11 +135,16 @@ export const docs = {
name: 'startContent',
type: 'ReactNode',
description: 'Content to render before the radio circle.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'endContent',
type: 'ReactNode',
description: 'Content to render after the label.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
],
},
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 535b416a99..9e5dcb9c63 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -4,6 +4,11 @@ export const docs = {
name: 'SegmentedControl',
group: 'SegmentedControl',
keywords: ['radio', 'tabs', 'toggle', 'toggle-group', 'pill', 'button-group', 'switch', 'segment', 'control'],
+ playground: {
+ defaults: {
+ value: 'option-1',
+ },
+ },
theming: {
targets: [
{className: 'xds-segmented-control', visualProps: ['size']},
@@ -65,6 +70,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'XDSSegmentedControlItem children.',
+ slotElements: [{__element: 'XDSSegmentedControlItem', props: {label: 'Option', value: 'option'}}],
required: true,
},
{
@@ -103,6 +109,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Icon element displayed before the label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'isDisabled',
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index aa91dc9ec4..3e74c26148 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -22,26 +22,31 @@ export const docs = {
name: 'header',
type: 'ReactNode',
description: 'Header area (typically XDSSideNavHeading). Sticky.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
},
{
name: 'topContent',
type: 'ReactNode',
description: 'Content below the header, e.g., a create button.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Top content'}],
},
{
name: 'children',
type: 'ReactNode',
description: 'Navigation sections and items. Scrollable.',
+ slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Nav Item'}}],
},
{
name: 'footer',
type: 'ReactNode',
description: 'Footer area above the icon bar.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
},
{
name: 'footerIcons',
type: 'ReactNode',
description: 'Footer icon bar.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'collapsible',
@@ -72,6 +77,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Product/app icon.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'headingHref',
@@ -102,11 +108,13 @@ export const docs = {
name: 'menu',
type: 'ReactNode',
description: 'Menu content rendered inside a popover.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
},
{
name: 'headerEndContent',
type: 'ReactNode',
description: 'Content rendered at the trailing edge of the heading row, between text and chevron. Useful for badges, status indicators, or compact action buttons. Hidden when collapsed.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
},
],
},
@@ -163,11 +171,16 @@ export const docs = {
name: 'endContent',
type: 'ReactNode',
description: 'Right-side content such as badges or counts.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'children',
type: 'ReactNode',
description: 'Sub-items for nesting.',
+ slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Sub Item'}}],
},
{
name: 'collapsible',
@@ -197,11 +210,16 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'Section items.',
+ slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Item'}}],
},
{
name: 'endContent',
type: 'ReactNode',
description: 'Right-side content in the section header.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'isHeaderHidden',
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index a18da1b713..9d48417eb6 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -4,6 +4,11 @@ export const docs = {
name: 'TabList',
group: 'Tabs',
keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],
+ playground: {
+ defaults: {
+ value: 'tab-1',
+ },
+ },
theming: {
targets: [
{className: 'xds-tab-list', visualProps: ['size']},
@@ -49,6 +54,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description: 'XDSTab and XDSTabMenu items to render inside the nav.',
+ slotElements: [{__element: 'XDSTab', props: {label: 'Tab', value: 'tab'}}],
required: true,
},
{
@@ -92,18 +98,24 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Icon element shown when the tab is not selected.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'selectedIcon',
type: 'ReactNode',
description:
'Icon element shown when the tab is selected; falls back to icon if not provided.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'checkCircle', size: 'sm'}}],
},
{
name: 'endContent',
type: 'ReactNode',
description:
'Content rendered after the label, such as a badge count or status dot.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'xstyle',
diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs
index 03a1dcfec1..65bc4d0189 100644
--- a/packages/core/src/Toast/Toast.doc.mjs
+++ b/packages/core/src/Toast/Toast.doc.mjs
@@ -12,6 +12,7 @@ export const docs = {
type: 'ReactNode',
description: 'Primary message content.',
required: true,
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Toast message'}],
},
{
name: 'type',
@@ -34,6 +35,10 @@ export const docs = {
name: 'endContent',
type: 'ReactNode',
description: 'Content rendered at the trailing end (e.g. Undo button, link).',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'uniqueID',
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 708f9fd665..ae03c64514 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -4,6 +4,12 @@ export const docs = {
name: 'ToggleButton',
group: 'Button',
keywords: ["toggle","togglebutton","pressed","toolbar","formatting","segmented","button-group","exclusive","multi-select"],
+ playground: {
+ defaults: {
+ value: 'option-1',
+ label: 'Toggle Group',
+ },
+ },
theming: {
targets: [
{className: 'xds-toggle-button-group'},
@@ -21,8 +27,12 @@ export const docs = {
{name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Button size. Defaults to group size when inside a group.', default: "'md'"},
{name: 'isDisabled', type: 'boolean', description: 'Whether the button is disabled.', default: 'false'},
{name: 'isLoading', type: 'boolean', description: 'Whether the button shows a loading spinner.', default: 'false'},
- {name: 'icon', type: 'ReactNode', description: 'Icon element. When provided without children, button becomes icon-only with tooltip from label.'},
- {name: 'pressedIcon', type: 'ReactNode', description: 'Icon shown when pressed. Falls back to icon if not provided.'},
+ {name: 'icon', type: 'ReactNode', description: 'Icon element. When provided without children, button becomes icon-only with tooltip from label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
+ {name: 'pressedIcon', type: 'ReactNode', description: 'Icon shown when pressed. Falls back to icon if not provided.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ },
{name: 'children', type: 'ReactNode', description: 'Visible content. If omitted with icon, button becomes icon-only.'},
{name: 'tooltip', type: 'string', description: 'Tooltip text shown on hover.'},
{name: 'value', type: 'string', description: 'Value identifier when used inside XDSToggleButtonGroup. Required in groups.'},
@@ -32,7 +42,7 @@ export const docs = {
name: 'XDSToggleButtonGroup',
description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
props: [
- {name: 'children', type: 'ReactNode', description: 'XDSToggleButton children.', required: true},
+ {name: 'children', type: 'ReactNode', description: 'XDSToggleButton children.', required: true, slotElements: [{__element: 'XDSToggleButton', props: {label: 'Option', value: 'option'}}]},
{name: 'label', type: 'string', description: 'Accessible label for the group (aria-label).', required: true},
{name: 'type', type: "'single' | 'multiple'", description: 'Selection mode. Single allows one active button, multiple allows many.', default: "'single'"},
{name: 'value', type: 'string | null | string[]', description: 'Currently selected value(s). Type depends on selection mode.', required: true},
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index bf57456e3d..c85f47db6a 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -26,6 +26,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Optional icon rendered before the label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'isDisabled',
@@ -63,6 +64,10 @@ export const docs = {
type: 'ReactNode',
description:
'Content rendered after the label and before the remove button.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'isLabelHidden',
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 74f4f2dc21..5ec4d75cb6 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -154,6 +154,10 @@ export const docs = {
type: 'ReactNode',
description:
'Content to display at the end of the input row. Useful for buttons, result counts, or other controls.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'xstyle',
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index 89a6af3754..366f1b53c7 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -24,17 +24,23 @@ export const docs = {
name: 'startContent',
type: 'ReactNode',
description: 'Content aligned to the start (left in LTR).',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'centerContent',
type: 'ReactNode',
description:
'Centered content. Switches layout to CSS grid (1fr auto 1fr).',
+ slotElements: [{__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'Center'}],
},
{
name: 'endContent',
type: 'ReactNode',
description: 'Content aligned to the end (right in LTR).',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'density',
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index c8a692324a..adab1ac8ec 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -22,6 +22,7 @@ export const docs = {
name: 'content',
type: 'ReactNode',
description: 'Tooltip content, typically short text.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Content text'}],
},
{
name: 'placement',
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index f2896f3c37..59eb6972c5 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -25,24 +25,31 @@ export const docs = {
type: 'ReactNode',
description:
'Heading slot content (logo, brand) — positioned at the left edge of the nav bar.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'Heading'}],
},
{
name: 'startContent',
type: 'ReactNode',
description:
'Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'centerContent',
type: 'ReactNode',
description:
'Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'Center'}],
},
{
name: 'endContent',
type: 'ReactNode',
description:
'End content slot for search, icons, or user profile — positioned at the right edge.',
+ slotElements: [
+ {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
+ {__element: 'XDSBadge', props: {label: '3'}},
+ ],
},
{
name: 'label',
@@ -67,6 +74,7 @@ export const docs = {
type: 'ReactNode',
description:
'Logo element to display before the heading text. Can be an image, XDSNavIcon, or any ReactNode.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'heading',
@@ -114,12 +122,14 @@ export const docs = {
type: 'ReactNode',
description:
'Content rendered at the trailing edge of the heading row (e.g. a badge or status indicator).',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
},
{
name: 'menu',
type: 'ReactNode',
description:
'Menu content shown in a popover dropdown. When provided, a chevron indicator appears automatically. Interaction boundary is determined by the presence of hrefs: no hrefs means the whole header is the trigger; with hrefs, links are independent and the chevron area is the trigger.',
+ slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
},
{
name: 'as',
@@ -178,6 +188,7 @@ export const docs = {
type: 'ReactNode',
description:
'Optional icon to display before the label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'children',
@@ -241,11 +252,13 @@ export const docs = {
name: 'items',
type: 'ReactNode',
description: 'Menu items slot — typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.',
+ slotElements: [{__element: 'XDSTopNavItem', props: {label: 'Item', href: '#'}}],
},
{
name: 'featured',
type: 'ReactNode',
description: 'Featured content slot — rendered in the right panel on desktop, below items in the mobile drawer.',
+ slotElements: [{__element: 'XDSCard', props: {padding: 4}, children: 'Featured content'}],
},
{
name: 'delay',
@@ -289,6 +302,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Optional icon element displayed to the left.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'href',
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 7575b63628..0c904ce783 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -4,6 +4,20 @@ export const docs = {
name: 'TreeList',
group: 'TreeList',
keywords: ['tree', 'hierarchy', 'nested', 'accordion', 'folder', 'expand', 'collapse', 'treeview', 'outline'],
+ playground: {
+ defaults: {
+ items: [
+ {id: '1', label: 'Documents', children: [
+ {id: '1a', label: 'Report.pdf'},
+ {id: '1b', label: 'Notes.md'},
+ ]},
+ {id: '2', label: 'Images', children: [
+ {id: '2a', label: 'Photo.jpg'},
+ ]},
+ {id: '3', label: 'README.md'},
+ ],
+ },
+ },
theming: {
targets: [
{className: 'xds-tree-list', visualProps: ['density']},
@@ -33,6 +47,7 @@ export const docs = {
type: 'ReactNode',
description:
'Header content, associated with the tree via aria-labelledby.',
+ slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
},
{
name: 'xstyle',
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 846b29383e..59788cdd72 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -272,6 +272,7 @@ export const docs = {
name: 'icon',
type: 'ReactNode',
description: 'Icon or avatar to display before the label.',
+ slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
},
{
name: 'description',