Skip to content

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

TypeScript

fix(docsite): derive icon editor options from registry (#2777)

Cindy Zhange906b76ab8c2
diff --git a/.changeset/checkbox-icon-prop-editor.md b/.changeset/checkbox-icon-prop-editor.md
new file mode 100644
index 0000000000..87286bf68c
--- /dev/null
+++ b/.changeset/checkbox-icon-prop-editor.md
@@ -0,0 +1,5 @@
+---
+'@xds/core': patch
+---
+
+`renderIconSlot` now renders semantic icon-name strings through `XDSIcon`, so icon slots that accept semantic names display the registry icon instead of plain text. The core Icon package also exposes `getIconRegistry()`, letting tooling and docs controls derive semantic icon-name options from the same registry `XDSIcon` resolves against.
diff --git a/apps/docsite/src/__tests__/component-prop-controls.test.ts b/apps/docsite/src/__tests__/component-prop-controls.test.ts
index 6fa2845a82..eb7bb107ec 100644
--- a/apps/docsite/src/__tests__/component-prop-controls.test.ts
+++ b/apps/docsite/src/__tests__/component-prop-controls.test.ts
@@ -1,5 +1,6 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {getIconRegistry} from '@xds/core/Icon';
import {describe, expect, it} from 'vitest';
import {parsePropType} from '../components/component-detail/parsePropType';
@@ -51,21 +52,15 @@ describe('component detail prop controls', () => {
});
});
- it('uses valid semantic icon options for XDSIconType props', () => {
+ it('derives XDSIconType options from the canonical icon registry', () => {
const control = parsePropType('XDSIconType', 'labelIcon');
expect(control).toMatchObject({
kind: 'enum',
allowEmpty: true,
});
- expect(control).toEqual(
- expect.objectContaining({
- options: expect.arrayContaining(['info', 'success', 'error', 'search']),
- }),
- );
if (control.kind === 'enum') {
- expect(control.options).not.toContain('checkCircle');
- expect(control.options).not.toContain('xCircle');
+ expect(control.options).toEqual(Object.keys(getIconRegistry()));
}
});
});
diff --git a/apps/docsite/src/components/component-detail/parsePropType.ts b/apps/docsite/src/components/component-detail/parsePropType.ts
index 5464af79c6..a0e269a15e 100644
--- a/apps/docsite/src/components/component-detail/parsePropType.ts
+++ b/apps/docsite/src/components/component-detail/parsePropType.ts
@@ -1,5 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {getIconRegistry} from '@xds/core/Icon';
+
/**
* Parses a stringified TypeScript prop type into a control descriptor
* that the playground can render an input for.
@@ -33,35 +35,6 @@ const CALLBACK_RE = /=>/;
const NODE_TYPE_RE = /\b(ReactNode|ReactElement|JSX\.Element|ReactChild)\b/;
const REACT_ELEMENT_RE = /ReactElement<(XDS\w+)Props>/g;
-const ICON_OPTIONS = [
- 'close',
- 'chevronDown',
- 'chevronLeft',
- 'chevronRight',
- 'check',
- 'success',
- 'error',
- 'warning',
- 'info',
- 'calendar',
- 'clock',
- 'externalLink',
- 'menu',
- 'moreHorizontal',
- 'search',
- 'arrowUp',
- 'arrowDown',
- 'arrowsUpDown',
- 'funnel',
- 'eyeSlash',
- 'viewColumns',
- 'copy',
- 'checkDouble',
- 'wrench',
- 'stop',
- 'microphone',
-];
-
const INPUT_STATUS_OPTIONS: InputStatusOption[] = [
'error',
'warning',
@@ -193,7 +166,7 @@ export function parsePropType(
if (t === 'XDSIconType' || t === 'XDSIconName') {
return {
kind: 'enum',
- options: ICON_OPTIONS,
+ options: Object.keys(getIconRegistry()),
allowEmpty: true,
};
}
diff --git a/packages/core/src/Icon/globalIconRegistry.test.tsx b/packages/core/src/Icon/globalIconRegistry.test.tsx
index d24c0e95dc..dec9084d98 100644
--- a/packages/core/src/Icon/globalIconRegistry.test.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.test.tsx
@@ -1,13 +1,27 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, beforeEach} from 'vitest';
-import {registerIcons, getIcon, resetIcons} from './globalIconRegistry';
+import {defaultIcons} from './defaultIcons';
+import {
+ registerIcons,
+ getIconRegistry,
+ getIcon,
+ resetIcons,
+} from './globalIconRegistry';
describe('iconRegistry (global, RSC-compatible)', () => {
beforeEach(() => {
resetIcons();
});
+ it('returns a default icon registry snapshot', () => {
+ const registry = getIconRegistry();
+
+ expect(Object.keys(registry)).toEqual(Object.keys(defaultIcons));
+ expect(registry).toEqual(defaultIcons);
+ expect(registry).not.toBe(defaultIcons);
+ });
+
it('returns default icons when nothing is registered', () => {
const icon = getIcon('close');
expect(icon).toBeDefined();
@@ -17,7 +31,10 @@ describe('iconRegistry (global, RSC-compatible)', () => {
it('returns registered icons over defaults', () => {
const customClose = 'custom-close-icon';
registerIcons({close: customClose});
+
expect(getIcon('close')).toBe(customClose);
+ expect(getIconRegistry().close).toBe(customClose);
+ expect(getIconRegistry().check).toBe(defaultIcons.check);
});
it('falls back to defaults for unregistered names', () => {
@@ -28,6 +45,13 @@ describe('iconRegistry (global, RSC-compatible)', () => {
expect(checkIcon).not.toBe('custom-close');
});
+ it('keeps registry snapshots aligned with getIcon fallback behavior', () => {
+ registerIcons({close: null});
+
+ expect(getIcon('close')).toBe(defaultIcons.close);
+ expect(getIconRegistry().close).toBe(defaultIcons.close);
+ });
+
it('merges multiple registerIcons calls', () => {
registerIcons({close: 'close-v1'});
registerIcons({check: 'check-v1'});
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index d35af1cf5e..49cadae5ba 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -3,7 +3,7 @@
/**
* @file globalIconRegistry.tsx
* @input None (pure module-level state)
- * @output Exports registerIcons, getIcon, resetIcons, XDSIconName, XDSIconRegistry
+ * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, XDSIconName, XDSIconRegistry
* @position Global icon registry; works in both server and client environments
*
* This module has NO 'use client' directive — it's importable from RSC.
@@ -81,6 +81,24 @@ export function registerIcons(icons: Partial<XDSIconRegistry>): void {
globalRegistry = {...globalRegistry, ...icons};
}
+/**
+ * Get a snapshot of the full icon registry, with registered icons overriding
+ * built-in defaults.
+ *
+ * Works in both server and client environments. Useful for tooling that needs
+ * to derive valid semantic icon-name options from the same registry XDSIcon
+ * resolves against.
+ */
+export function getIconRegistry(): Readonly<XDSIconRegistry> {
+ const registry = {...defaultIcons};
+
+ for (const name of Object.keys(globalRegistry) as XDSIconName[]) {
+ registry[name] = globalRegistry[name] ?? defaultIcons[name];
+ }
+
+ return registry;
+}
+
/**
* Get an icon by name from the global registry, falling back to defaults.
*
diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.ts
index 3cb321e82e..2c916b33c0 100644
--- a/packages/core/src/Icon/index.ts
+++ b/packages/core/src/Icon/index.ts
@@ -5,7 +5,7 @@
/**
* @file index.ts
* @input Imports XDSIcon component/types, icon registry, and global registration
- * @output Exports XDSIcon, icon registry, registerIcons, getIcon
+ * @output Exports XDSIcon, icon registry helpers, registerIcons, getIconRegistry, getIcon
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
* SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
@@ -20,5 +20,10 @@ export type {
} from './XDSIcon';
// Global registry (RSC-compatible, no 'use client')
-export {registerIcons, getIcon, resetIcons} from './globalIconRegistry';
+export {
+ registerIcons,
+ getIconRegistry,
+ getIcon,
+ resetIcons,
+} from './globalIconRegistry';
export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';