Skip to content

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

TypeScript

fix(docsite): harden component property previews (#2782)

Cindy Zhang4c3ec831ac39
diff --git a/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
new file mode 100644
index 0000000000..b932644e19
--- /dev/null
+++ b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {isValidElement, type ReactElement} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {resolveValue} from '../components/component-detail/resolveElements';
+
+vi.mock('@xds/core', () => ({
+ XDSBadge: () => null,
+ XDSIcon: () => null,
+ XDSSideNavItem: () => null,
+}));
+
+describe('component detail element resolution', () => {
+ it('resolves descriptor arrays from playground defaults into React elements', () => {
+ const resolved = resolveValue([
+ {__element: 'XDSSideNavItem', props: {label: 'Dashboard'}},
+ {__element: 'XDSSideNavItem', props: {label: 'Projects'}},
+ ]);
+
+ expect(Array.isArray(resolved)).toBe(true);
+ const items = resolved as ReactElement<Record<string, unknown>>[];
+ expect(items.every(item => isValidElement(item))).toBe(true);
+ expect(items[0].props).toMatchObject({label: 'Dashboard'});
+ expect(items[1].props).toMatchObject({label: 'Projects'});
+ });
+
+ it('resolves descriptors nested inside plain object props', () => {
+ const resolved = resolveValue({
+ before: {__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}},
+ children: [{__element: 'XDSBadge', props: {label: '3'}}],
+ }) as {
+ before: ReactElement<Record<string, unknown>>;
+ children: ReactElement<Record<string, unknown>>[];
+ };
+
+ expect(isValidElement(resolved.before)).toBe(true);
+ expect(resolved.before.props).toMatchObject({icon: 'check', size: 'sm'});
+ expect(isValidElement(resolved.children[0])).toBe(true);
+ expect(resolved.children[0].props).toMatchObject({label: '3'});
+ });
+});
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
new file mode 100644
index 0000000000..2b799e9f93
--- /dev/null
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it, vi} from 'vitest';
+import {
+ buildInitialState,
+ getMissingRequiredProps,
+ pickPrimaryProps,
+} from '../components/component-detail/interactiveState';
+import type {PropDoc} from '../generated/componentRegistry';
+
+vi.mock('@xds/core', () => ({}));
+vi.mock('@xds/core/theme/syntax', () => ({allSyntaxPresets: []}));
+vi.mock('../generated/themeRegistry', () => ({themeObjectsFull: {}}));
+
+function prop(
+ partial: Partial<PropDoc> & Pick<PropDoc, 'name' | 'type'>,
+): PropDoc {
+ return {
+ description: '',
+ ...partial,
+ };
+}
+
+describe('component detail preview state', () => {
+ it('generates safe runtime defaults for typeahead-like required props', async () => {
+ const knobs = pickPrimaryProps('BaseTypeahead', [
+ prop({name: 'searchSource', type: 'XDSSearchSource<T>', required: true}),
+ prop({name: 'value', type: 'T | null', required: true}),
+ prop({
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ required: true,
+ }),
+ ]);
+
+ const state = buildInitialState(knobs);
+
+ expect(state.value).toBeNull();
+ expect(state.onChange).toEqual(expect.any(Function));
+ expect(state.searchSource).toMatchObject({
+ search: expect.any(Function),
+ bootstrap: expect.any(Function),
+ cancel: expect.any(Function),
+ });
+ await expect(
+ Promise.resolve(
+ (state.searchSource as {search: (query: string) => unknown}).search(
+ 'proj',
+ ),
+ ),
+ ).resolves.toEqual([{id: 'projects', label: 'Projects'}]);
+ expect(getMissingRequiredProps(knobs, state)).toEqual([]);
+ });
+
+ it('reports required props that cannot be generated safely', () => {
+ const knobs = pickPrimaryProps('CustomWidget', [
+ prop({name: 'config', type: 'CustomConfig', required: true}),
+ ]);
+ const state = buildInitialState(knobs);
+
+ expect(state.config).toBeUndefined();
+ expect(getMissingRequiredProps(knobs, state)).toEqual(['config']);
+ });
+});
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index e61a7d79c7..810133db1e 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -142,7 +142,7 @@ function ComponentDetailInner({
router.replace(`${pathname}${qs ? `?${qs}` : ''}`, {scroll: false});
};
- const {knobs, state, setProp} = useInteractiveState(
+ const {knobs, state, setProp, missingRequiredProps} = useInteractiveState(
comp.name,
comp.props,
comp.playground,
@@ -192,7 +192,11 @@ function ComponentDetailInner({
maxHeight: isMobile ? 250 : 400,
overflow: 'auto',
}}>
- <InteractivePreviewStage name={comp.name} state={state} />
+ <InteractivePreviewStage
+ name={comp.name}
+ state={state}
+ missingRequiredProps={missingRequiredProps}
+ />
</div>
{comp.props.length > 0 && (
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index 46384b32d6..e8709f8ebd 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -11,7 +11,7 @@ import {
Component,
type ReactNode,
} from 'react';
-import {getXDSComponent, resolveValue} from './resolveElements';
+import {getXDSComponent} from './resolveElements';
import {XDSButton} from '@xds/core/Button';
import {XDSCard} from '@xds/core/Card';
import {XDSCenter} from '@xds/core/Center';
@@ -19,25 +19,20 @@ import {CodeExampleBlock} from '../CodeExampleBlock';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {XDSTheme} from '@xds/core/theme';
-import {allSyntaxPresets} from '@xds/core/theme/syntax';
import {neutralTheme} from '@xds/theme-neutral/built';
-import {themeObjectsFull} from '../../generated/themeRegistry';
import {useThemeMode} from '../../app/providers';
import {Code} from 'lucide-react';
import {
- coerceDefault,
- parsePropType,
- type PropControlDescriptor,
-} from './parsePropType';
+ buildInitialState,
+ getMissingRequiredProps,
+ pickPrimaryProps,
+} from './interactiveState';
import type {
PropDoc,
PlaygroundConfig,
} from '../../generated/componentRegistry';
-export interface KnobProp {
- row: PropDoc;
- control: PropControlDescriptor;
-}
+export type {KnobProp} from './interactiveState';
class PreviewErrorBoundary extends Component<
{children: ReactNode; resetKeys: unknown[]},
@@ -67,129 +62,6 @@ class PreviewErrorBoundary extends Component<
}
}
-function pickPrimaryProps(name: string, props: PropDoc[]): KnobProp[] {
- if (props.length === 0) {
- return [];
- }
- return props.map(row => ({
- row,
- control: parsePropType(row.type, row.name, row.slotElements),
- }));
-}
-
-function resolveThemeValue(value: unknown): unknown {
- if (typeof value !== 'string') {
- return resolveValue(value);
- }
-
- const byPackageName = themeObjectsFull[value];
- if (byPackageName) {
- return byPackageName;
- }
-
- return (
- Object.values(themeObjectsFull).find(theme => theme.name === value) ?? value
- );
-}
-
-function resolveSyntaxThemeValue(value: unknown): unknown {
- if (typeof value !== 'string') {
- return resolveValue(value);
- }
-
- return allSyntaxPresets.find(theme => theme.name === value) ?? value;
-}
-
-function resolveDefaultValue(
- value: unknown,
- control: PropControlDescriptor | undefined,
-): unknown {
- if (control?.kind === 'theme') {
- return resolveThemeValue(value);
- }
- if (control?.kind === 'syntax-theme') {
- return resolveSyntaxThemeValue(value);
- }
- return resolveValue(value);
-}
-
-function buildInitialState(
- knobs: KnobProp[],
- playground?: PlaygroundConfig | null,
-): Record<string, unknown> {
- const state: Record<string, unknown> = {};
-
- const controlByName = new Map(
- knobs.map(({row, control}) => [row.name, control]),
- );
-
- // Apply playground defaults first (resolved from ElementDescriptor if needed)
- if (playground?.defaults) {
- for (const [key, value] of Object.entries(playground.defaults)) {
- state[key] = resolveDefaultValue(value, controlByName.get(key));
- }
- }
-
- // Fill in remaining props from doc defaults / auto-generation
- for (const {row, control} of knobs) {
- if (state[row.name] !== undefined) {
- continue;
- }
- 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':
- state[row.name] = control.options[0];
- break;
- case 'theme':
- state[row.name] = Object.values(themeObjectsFull)[0];
- break;
- case 'syntax-theme':
- state[row.name] = allSyntaxPresets[0];
- break;
- case 'input-status':
- state[row.name] = {
- type: control.options[0],
- message: `${control.options[0]} status`,
- };
- break;
- case 'boolean':
- state[row.name] = false;
- break;
- case 'string':
- state[row.name] = row.name;
- break;
- case 'number':
- state[row.name] = 0;
- break;
- }
- }
- }
- return state;
-}
-
function toIdentifierName(name: string): string {
return name
.split(/[^a-zA-Z0-9]+/)
@@ -292,6 +164,10 @@ export function useInteractiveState(
[knobs, playground],
);
const [state, setState] = useState<Record<string, unknown>>(initialState);
+ const missingRequiredProps = useMemo(
+ () => getMissingRequiredProps(knobs, initialState),
+ [knobs, initialState],
+ );
const setProp = useCallback(
(propName: string, value: unknown) =>
@@ -306,20 +182,46 @@ export function useInteractiveState(
[state, initialState],
);
- return {knobs, state, setProp, reset, isDirty};
+ return {knobs, state, setProp, reset, isDirty, missingRequiredProps};
}
export function InteractivePreviewStage({
name,
state,
+ missingRequiredProps = [],
}: {
name: string;
state: Record<string, unknown>;
+ missingRequiredProps?: string[];
}) {
const {mode} = useThemeMode();
const [showCode, setShowCode] = useState(false);
const Component = getXDSComponent(name);
+ if (missingRequiredProps.length > 0) {
+ return (
+ <XDSCard variant="muted" padding={0}>
+ <XDSCenter style={{minHeight: 200, width: '100%'}}>
+ <XDSVStack
+ gap={1}
+ style={{
+ paddingBlock: 24,
+ paddingInline: 16,
+ textAlign: 'center',
+ }}>
+ <XDSText type="supporting" color="secondary">
+ Interactive preview needs required props that cannot be generated
+ automatically.
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Missing: {missingRequiredProps.join(', ')}
+ </XDSText>
+ </XDSVStack>
+ </XDSCenter>
+ </XDSCard>
+ );
+ }
+
if (!Component) {
return (
<XDSCard variant="muted" padding={0}>
diff --git a/apps/docsite/src/components/component-detail/interactiveState.ts b/apps/docsite/src/components/component-detail/interactiveState.ts
new file mode 100644
index 0000000000..e5a8ce21e8
--- /dev/null
+++ b/apps/docsite/src/components/component-detail/interactiveState.ts
@@ -0,0 +1,206 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Builds the initial prop state for component detail interactive previews.
+ * Keeps runtime-only defaults (callbacks, mock search sources, descriptor
+ * resolution) out of the generated JSON registries.
+ */
+
+import {allSyntaxPresets} from '@xds/core/theme/syntax';
+import {themeObjectsFull} from '../../generated/themeRegistry';
+import {
+ coerceDefault,
+ parsePropType,
+ type PropControlDescriptor,
+} from './parsePropType';
+import {resolveValue} from './resolveElements';
+import type {
+ PropDoc,
+ PlaygroundConfig,
+} from '../../generated/componentRegistry';
+
+export interface KnobProp {
+ row: PropDoc;
+ control: PropControlDescriptor;
+}
+
+const PREVIEW_SEARCH_ITEMS = [
+ {id: 'dashboard', label: 'Dashboard'},
+ {id: 'projects', label: 'Projects'},
+ {id: 'settings', label: 'Settings'},
+];
+
+const PREVIEW_SEARCH_SOURCE = {
+ search(query: string) {
+ const normalized = query.trim().toLowerCase();
+ if (normalized === '') {
+ return PREVIEW_SEARCH_ITEMS;
+ }
+ return PREVIEW_SEARCH_ITEMS.filter(item =>
+ item.label.toLowerCase().includes(normalized),
+ );
+ },
+ bootstrap() {
+ return PREVIEW_SEARCH_ITEMS;
+ },
+ cancel() {},
+};
+
+export function pickPrimaryProps(name: string, props: PropDoc[]): KnobProp[] {
+ if (props.length === 0) {
+ return [];
+ }
+ return props.map(row => ({
+ row,
+ control: parsePropType(row.type, row.name, row.slotElements),
+ }));
+}
+
+function resolveThemeValue(value: unknown): unknown {
+ if (typeof value !== 'string') {
+ return resolveValue(value);
+ }
+
+ const byPackageName = themeObjectsFull[value];
+ if (byPackageName) {
+ return byPackageName;
+ }
+
+ return (
+ Object.values(themeObjectsFull).find(theme => theme.name === value) ?? value
+ );
+}
+
+function resolveSyntaxThemeValue(value: unknown): unknown {
+ if (typeof value !== 'string') {
+ return resolveValue(value);
+ }
+
+ return allSyntaxPresets.find(theme => theme.name === value) ?? value;
+}
+
+function resolveDefaultValue(
+ value: unknown,
+ control: PropControlDescriptor | undefined,
+): unknown {
+ if (control?.kind === 'theme') {
+ return resolveThemeValue(value);
+ }
+ if (control?.kind === 'syntax-theme') {
+ return resolveSyntaxThemeValue(value);
+ }
+ return resolveValue(value);
+}
+
+function getRequiredFallbackValue(
+ row: PropDoc,
+ control: PropControlDescriptor,
+): unknown {
+ switch (control.kind) {
+ case 'enum':
+ return control.options[0];
+ case 'theme':
+ return Object.values(themeObjectsFull)[0];
+ case 'syntax-theme':
+ return allSyntaxPresets[0];
+ case 'input-status':
+ return {
+ type: control.options[0],
+ message: `${control.options[0]} status`,
+ };
+ case 'boolean':
+ return false;
+ case 'string':
+ return row.name;
+ case 'number':
+ return 0;
+ case 'callback':
+ return () => {};
+ case 'element':
+ return row.slotElements?.[0] != null
+ ? resolveValue(row.slotElements[0])
+ : undefined;
+ case 'slot-list':
+ return buildSlotListDefault(row);
+ case 'unknown':
+ if (/\bXDSSearchSource\b/.test(row.type)) {
+ return PREVIEW_SEARCH_SOURCE;
+ }
+ if (/\bnull\b/.test(row.type)) {
+ return null;
+ }
+ return undefined;
+ }
+}
+
+function buildSlotListDefault(row: PropDoc): unknown[] | undefined {
+ const slotEl = row.slotElements?.[0];
+ if (!slotEl) {
+ return undefined;
+ }
+ return [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);
+ });
+}
+
+export function buildInitialState(
+ knobs: KnobProp[],
+ playground?: PlaygroundConfig | null,
+): Record<string, unknown> {
+ const state: Record<string, unknown> = {};
+
+ const controlByName = new Map(
+ knobs.map(({row, control}) => [row.name, control]),
+ );
+
+ // Apply playground defaults first (resolved from ElementDescriptor if needed)
+ if (playground?.defaults) {
+ for (const [key, value] of Object.entries(playground.defaults)) {
+ state[key] = resolveDefaultValue(value, controlByName.get(key));
+ }
+ }
+
+ // Fill in remaining props from doc defaults / auto-generation
+ for (const {row, control} of knobs) {
+ if (state[row.name] !== undefined) {
+ continue;
+ }
+ 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 slotList = buildSlotListDefault(row);
+ if (slotList !== undefined) {
+ state[row.name] = slotList;
+ }
+ } else if (row.required) {
+ const fallback = getRequiredFallbackValue(row, control);
+ if (fallback !== undefined) {
+ state[row.name] = fallback;
+ }
+ }
+ }
+ return state;
+}
+
+export function getMissingRequiredProps(
+ knobs: KnobProp[],
+ state: Record<string, unknown>,
+): string[] {
+ return knobs
+ .filter(({row}) => row.required === true && state[row.name] === undefined)
+ .map(({row}) => row.name);
+}
diff --git a/apps/docsite/src/components/component-detail/resolveElements.ts b/apps/docsite/src/components/component-detail/resolveElements.ts
index 20032efa8a..a2b968d98a 100644
--- a/apps/docsite/src/components/component-detail/resolveElements.ts
+++ b/apps/docsite/src/components/component-detail/resolveElements.ts
@@ -6,7 +6,12 @@
* PlaygroundPropsTable (for slot element controls).
*/
-import {createElement, type ComponentType} from 'react';
+import {
+ cloneElement,
+ createElement,
+ isValidElement,
+ type ComponentType,
+} from 'react';
import * as XDSCore from '@xds/core';
import type {ElementDescriptor} from '../../generated/componentRegistry';
@@ -25,36 +30,39 @@ export function isElementDescriptor(v: unknown): v is ElementDescriptor {
return v != null && typeof v === 'object' && '__element' in v;
}
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+ if (v == null || typeof v !== 'object' || isValidElement(v)) {
+ return false;
+ }
+ const proto = Object.getPrototypeOf(v);
+ return proto === Object.prototype || proto === null;
+}
+
+function withArrayKey(node: unknown, key: number): unknown {
+ if (isValidElement(node) && node.key == null) {
+ return cloneElement(node, {key});
+ }
+ return node;
+}
+
export function resolveElementDescriptor(
desc: ElementDescriptor,
): React.ReactNode {
const Comp = getXDSComponent(desc.__element.replace(/^XDS/, ''));
const tag = Comp ?? desc.__element;
- // Resolve any nested ElementDescriptors inside props
+ // Resolve nested ElementDescriptors anywhere 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;
+ resolvedProps[key] = resolveValue(val);
}
}
- 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);
- }
- }
+ const children =
+ desc.children == null
+ ? undefined
+ : (resolveValue(desc.children) as React.ReactNode);
return createElement(tag, resolvedProps, children);
}
@@ -63,5 +71,21 @@ export function resolveValue(v: unknown): unknown {
if (isElementDescriptor(v)) {
return resolveElementDescriptor(v);
}
+
+ if (Array.isArray(v)) {
+ return v.map((item, index) => withArrayKey(resolveValue(item), index));
+ }
+
+ if (isPlainObject(v)) {
+ const resolved: Record<string, unknown> = {};
+ let changed = false;
+ for (const [key, value] of Object.entries(v)) {
+ const next = resolveValue(value);
+ resolved[key] = next;
+ changed ||= next !== value;
+ }
+ return changed ? resolved : v;
+ }
+
return v;
}