An open source design system that's fully customizable and agent ready
TypeScript
feat(core): add module-level registerIcons() for RSC compatibility (#528)
Cindy Zhang44a8529e1d54
diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsxindex f19f14891e..d505588fc0 100644--- a/packages/core/src/Icon/IconRegistry.tsx+++ b/packages/core/src/Icon/IconRegistry.tsx@@ -1,55 +1,27 @@/*** @file IconRegistry.tsx- * @input Uses React createContext, useContext, ReactNode- * @output Exports IconRegistryContext, useXDSIcon hook, XDSIconName, XDSIconRegistry types- * @position Core icon infrastructure; consumed by components that need internal icons+ * @input Uses React createContext, useContext+ * @output Exports IconRegistryContext, useXDSIcon hook+ * @position Client-side icon context; wraps the global registry with+ * React Context support for tree-scoped overrides via XDSTheme.+ *+ * For server components, use getIcon() from globalIconRegistry.tsx instead.** SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Icon/globalIconRegistry.tsx (global registry, types)* - /packages/core/src/Icon/Icon.doc.mjs (features, usage)* - /packages/core/src/Icon/index.ts (exports)- * - /packages/core/src/Icon/defaultIcons.tsx (fallback icon set)*/'use client';import {createContext, useContext, type ReactNode} from 'react';import {defaultIcons} from './defaultIcons';+import type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';+import {getGlobalRegistry} from './globalIconRegistry';-// =============================================================================-// Types-// =============================================================================--/**- * Semantic icon names used internally by XDS components.- *- * These represent the functional purpose of each icon, not a specific- * visual representation. Themes provide the actual icon components.- */-export type XDSIconName =- | 'close'- | 'chevronDown'- | 'chevronLeft'- | 'chevronRight'- | 'check'- | 'checkCircle'- | 'xCircle'- | 'warning'- | 'info'- | 'calendar'- | 'clock'- | 'externalLink'- | 'menu'- | 'moreHorizontal'- | 'search';--/**- * Icon registry mapping semantic names to React nodes.- *- * Themes provide this to override the built-in fallback icons.- * Values can be any ReactNode: SVG components, font icon spans,- * unicode characters, or any other renderable content.- */-export type XDSIconRegistry = Record<XDSIconName, ReactNode>;+// Re-export types so existing imports from this file still work+export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';// =============================================================================// Context@@ -58,7 +30,7 @@ export type XDSIconRegistry = Record<XDSIconName, ReactNode>;/*** Context for providing theme icons to components.* Accepts a full or partial registry. When null, components fall back- * to built-in lightweight SVGs. Partial registries fall back per-icon.+ * to the global registry, then to built-in lightweight SVGs.*/export const IconRegistryContext =createContext<Partial<XDSIconRegistry> | null>(null);@@ -68,24 +40,34 @@ export const IconRegistryContext =// =============================================================================/**- * Hook to retrieve an icon by semantic name.+ * Hook to retrieve an icon by semantic name (client components only).** Resolution order:- * 1. Theme icon registry (via IconRegistryContext) — if the name exists- * 2. Built-in lightweight SVG fallback+ * 1. Context registry (via XDSTheme's IconRegistryContext)+ * 2. Global registry (via registerIcons())+ * 3. Built-in lightweight SVG fallback+ *+ * For server components, use getIcon() from iconRegistry.ts instead.** @example* ```* const closeIcon = useXDSIcon('close');- * // Returns the theme's close icon, or the built-in SVG fallback* ```*/export function useXDSIcon(name: XDSIconName): ReactNode {- const registry = useContext(IconRegistryContext);+ const contextRegistry = useContext(IconRegistryContext);+ const globalRegistry = getGlobalRegistry();++ // Context wins (tree-scoped theme override)+ if (contextRegistry != null && contextRegistry[name] != null) {+ return contextRegistry[name];+ }- if (registry != null && registry[name] != null) {- return registry[name];+ // Global registry (module-level, works server-side too)+ if (globalRegistry[name] != null) {+ return globalRegistry[name];}+ // Built-in fallbackreturn defaultIcons[name];}diff --git a/packages/core/src/Icon/globalIconRegistry.test.tsx b/packages/core/src/Icon/globalIconRegistry.test.tsxnew file mode 100644index 0000000000..bf79871a41--- /dev/null+++ b/packages/core/src/Icon/globalIconRegistry.test.tsx@@ -0,0 +1,49 @@+import {describe, it, expect, beforeEach} from 'vitest';+import {registerIcons, getIcon, resetIcons} from './globalIconRegistry';++describe('iconRegistry (global, RSC-compatible)', () => {+ beforeEach(() => {+ resetIcons();+ });++ it('returns default icons when nothing is registered', () => {+ const icon = getIcon('close');+ expect(icon).toBeDefined();+ expect(icon).not.toBeNull();+ });++ it('returns registered icons over defaults', () => {+ const customClose = 'custom-close-icon';+ registerIcons({close: customClose});+ expect(getIcon('close')).toBe(customClose);+ });++ it('falls back to defaults for unregistered names', () => {+ registerIcons({close: 'custom-close'});+ // 'check' was not registered, should fall back to default+ const checkIcon = getIcon('check');+ expect(checkIcon).toBeDefined();+ expect(checkIcon).not.toBe('custom-close');+ });++ it('merges multiple registerIcons calls', () => {+ registerIcons({close: 'close-v1'});+ registerIcons({check: 'check-v1'});+ expect(getIcon('close')).toBe('close-v1');+ expect(getIcon('check')).toBe('check-v1');+ });++ it('later registrations override earlier ones', () => {+ registerIcons({close: 'close-v1'});+ registerIcons({close: 'close-v2'});+ expect(getIcon('close')).toBe('close-v2');+ });++ it('resetIcons clears the global registry', () => {+ registerIcons({close: 'custom'});+ expect(getIcon('close')).toBe('custom');+ resetIcons();+ // Should fall back to default+ expect(getIcon('close')).not.toBe('custom');+ });+});diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsxnew file mode 100644index 0000000000..1797db1a36--- /dev/null+++ b/packages/core/src/Icon/globalIconRegistry.tsx@@ -0,0 +1,99 @@+/**+ * @file globalIconRegistry.tsx+ * @input None (pure module-level state)+ * @output Exports registerIcons, 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.+ * Components that need icons in server components use getIcon() directly.+ * Client components use useXDSIcon() from IconRegistryContext.tsx which+ * checks context first, then falls back to this global registry.+ */++import type {ReactNode} from 'react';+import {defaultIcons} from './defaultIcons';++// =============================================================================+// Types+// =============================================================================++/**+ * Semantic icon names used internally by XDS components.+ *+ * These represent the functional purpose of each icon, not a specific+ * visual representation. Themes provide the actual icon components.+ */+export type XDSIconName =+ | 'close'+ | 'chevronDown'+ | 'chevronLeft'+ | 'chevronRight'+ | 'check'+ | 'checkCircle'+ | 'xCircle'+ | 'warning'+ | 'info'+ | 'calendar'+ | 'clock'+ | 'externalLink'+ | 'menu'+ | 'moreHorizontal'+ | 'search';++/**+ * Icon registry mapping semantic names to React nodes.+ */+export type XDSIconRegistry = Record<XDSIconName, ReactNode>;++// =============================================================================+// Global Registry+// =============================================================================++let globalRegistry: Partial<XDSIconRegistry> = {};++/**+ * Register icons at the module level. Works in both server and client+ * environments. Call once at app initialization (e.g. root layout).+ *+ * Icons registered here are available to all components — including+ * server-rendered ones that can't access React Context.+ *+ * @example+ * ```ts+ * // app/layout.tsx (RSC-compatible)+ * import { registerIcons } from '@xds/core';+ * import { brandIcons } from './brand-icons';+ *+ * registerIcons(brandIcons);+ * ```+ */+export function registerIcons(icons: Partial<XDSIconRegistry>): void {+ globalRegistry = {...globalRegistry, ...icons};+}++/**+ * Get an icon by name from the global registry, falling back to defaults.+ *+ * Use this in server components where hooks aren't available.+ * In client components, prefer useXDSIcon() which also checks+ * the React Context registry.+ */+export function getIcon(name: XDSIconName): ReactNode {+ return globalRegistry[name] ?? defaultIcons[name];+}++/**+ * Get the raw global registry (internal use by useXDSIcon).+ * @internal+ */+export function getGlobalRegistry(): Partial<XDSIconRegistry> {+ return globalRegistry;+}++/**+ * Reset the global registry. For testing only.+ * @internal+ */+export function resetIcons(): void {+ globalRegistry = {};+}diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.tsindex 642f72ade0..de547cb4ab 100644--- a/packages/core/src/Icon/index.ts+++ b/packages/core/src/Icon/index.ts@@ -1,7 +1,7 @@/*** @file index.ts- * @input Imports XDSIcon component/types and IconRegistry types- * @output Exports XDSIcon, its prop types, icon registry context, and semantic name types+ * @input Imports XDSIcon component/types, icon registry, and global registration+ * @output Exports XDSIcon, icon registry, registerIcons, 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@@ -14,5 +14,10 @@ export type {XDSIconSize,XDSIconType,} from './XDSIcon';-export type {XDSIconName, XDSIconRegistry} from './IconRegistry';-export {IconRegistryContext} from './IconRegistry';++// Global registry (RSC-compatible, no 'use client')+export {registerIcons, getIcon, resetIcons} from './globalIconRegistry';+export type {XDSIconName, XDSIconRegistry} from './globalIconRegistry';++// Context registry (client-only)+export {IconRegistryContext, useXDSIcon} from './IconRegistry';diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsxindex c765fdf9b5..13276f4d8d 100644--- a/packages/core/src/theme/XDSTheme.tsx+++ b/packages/core/src/theme/XDSTheme.tsx@@ -30,6 +30,7 @@ import * as stylex from '@stylexjs/stylex';import type {ThemeMode} from './types';import {colorVars, typographyVars} from './tokens.stylex';import {IconRegistryContext} from '../Icon/IconRegistry';+import {registerIcons} from '../Icon/globalIconRegistry';import {generateThemeCSS, type XDSDefinedTheme} from './defineTheme';/**@@ -134,10 +135,11 @@ export function XDSTheme({? wrapperStyles.light: wrapperStyles.system;- // Icons+ // Icons — register globally (for server components) AND via context (for tree-scoped overrides)const icons = theme.icons;let content: React.ReactNode = children;if (icons != null) {+ registerIcons(icons);content = (<IconRegistryContext.Provider value={icons}>{content}