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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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;}