Skip to content

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

TypeScript

fix(docsite): reuse sidebar component search source (#2779)

Cindy Zhang5f0dbe76d72d
diff --git a/apps/docsite/src/__tests__/search-palette.test.ts b/apps/docsite/src/__tests__/search-palette.test.ts
new file mode 100644
index 0000000000..7c47748c35
--- /dev/null
+++ b/apps/docsite/src/__tests__/search-palette.test.ts
@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Search palette data tests.
+ *
+ * Validates that the global docsite command palette indexes the same component
+ * links as the sidebar.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {components} from '../generated/componentRegistry';
+import {packages} from '../generated/packageRegistry';
+import {docTopics} from '../generated/docsRegistry';
+import {templates} from '../generated/templateRegistry';
+import {flattenComponentSidebarEntries} from '../components/componentSidebarData';
+import {
+ buildSearchPaletteItems,
+ getSearchItemKeywords,
+} from '../components/searchPaletteData';
+
+function buildItems() {
+ return buildSearchPaletteItems({
+ components,
+ packages,
+ docTopics,
+ templates,
+ });
+}
+
+function searchItems(query: string) {
+ const lower = query.toLowerCase().trim();
+ return buildItems().filter(
+ item =>
+ item.label.toLowerCase().includes(lower) ||
+ getSearchItemKeywords(item).some(kw => kw.toLowerCase().includes(lower)),
+ );
+}
+
+describe('SearchPalette data', () => {
+ it('uses the sidebar entries as the command palette component set', () => {
+ const componentIds = buildItems()
+ .filter(item => item.auxiliaryData.group === 'Component')
+ .map(item => item.id);
+ const sidebarIds = flattenComponentSidebarEntries().map(
+ entry => entry.href,
+ );
+
+ expect(new Set(componentIds).size).toBe(componentIds.length);
+ expect(new Set(componentIds)).toEqual(new Set(sidebarIds));
+ expect(componentIds).toContain('/components/DropdownMenu');
+ expect(componentIds).toContain('/components/DropdownMenuItem');
+ expect(componentIds).toContain('/components/CommandPalette');
+ expect(componentIds).toContain('/components/Table');
+ });
+
+ it('finds Dropdown Menu by spaced display name and PascalCase API name', () => {
+ const items = buildItems();
+ const dropdown = items.find(item => item.id === '/components/DropdownMenu');
+ expect(dropdown?.label).toBe('Dropdown Menu');
+
+ expect(searchItems('dropdown menu').map(item => item.id)).toContain(
+ '/components/DropdownMenu',
+ );
+ expect(searchItems('DropdownMenu').map(item => item.id)).toContain(
+ '/components/DropdownMenu',
+ );
+ });
+});
diff --git a/apps/docsite/src/app/(docs)/components/[name]/page.tsx b/apps/docsite/src/app/(docs)/components/[name]/page.tsx
index d061fd29de..74f10ed3b0 100644
--- a/apps/docsite/src/app/(docs)/components/[name]/page.tsx
+++ b/apps/docsite/src/app/(docs)/components/[name]/page.tsx
@@ -11,11 +11,12 @@ import {components} from '../../../../generated/componentRegistry';
import {blocks} from '../../../../generated/blockRegistry';
import {packages} from '../../../../generated/packageRegistry';
import {ComponentDetailClient} from '../../../../components/component-detail/ComponentDetailClient';
+import {flattenComponentSidebarEntries} from '../../../../components/componentSidebarData';
const allComponents = Object.values(components).flat();
export function generateStaticParams() {
- return allComponents.filter(c => !c.parentDoc).map(c => ({name: c.name}));
+ return flattenComponentSidebarEntries().map(c => ({name: c.name}));
}
export default async function ComponentPage({
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index b3f73734e8..5da96e5c18 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -13,11 +13,8 @@ import type {ComponentEntry} from '../generated/componentRegistry';
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
import type {TemplateEntry} from '../generated/templateRegistry';
-import type {
- ComponentItem,
- GroupedEntry,
-} from '../generated/groupedComponentRegistry';
-import {groupedComponents} from '../generated/groupedComponentRegistry';
+import type {GroupedEntry} from '../generated/groupedComponentRegistry';
+import {getComponentSidebarData} from './componentSidebarData';
interface DocsShellProps {
children: React.ReactNode;
@@ -39,21 +36,6 @@ const foundationsSort = (a: DocTopic, b: DocTopic) => {
return a.title.localeCompare(b.title);
};
-// ── Component sidebar builder ──────────────────────────────────────────
-
-type SidebarItem = ComponentItem;
-
-function buildComponentSidebar(): {
- componentItems: SidebarItem[];
- utilities: Array<{name: string; displayName: string; href: string}>;
-} {
- const grouped = groupedComponents['@xds/core'];
- if (!grouped) {
- return {componentItems: [], utilities: []};
- }
- return {componentItems: grouped.items, utilities: grouped.utilities};
-}
-
// ── Shell ──────────────────────────────────────────────────────────────
export function DocsShell({
@@ -67,7 +49,7 @@ export function DocsShell({
const pathname = usePathname();
const [componentQuery, setComponentQuery] = useState('');
- const {componentItems, utilities} = buildComponentSidebar();
+ const {componentItems, utilities} = getComponentSidebarData();
const q = componentQuery.trim().toLowerCase();
diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsx
index ce6f7b420a..0aa18c3770 100644
--- a/apps/docsite/src/components/SearchPalette.tsx
+++ b/apps/docsite/src/components/SearchPalette.tsx
@@ -6,18 +6,15 @@ import {useMemo, useCallback} from 'react';
import {useRouter} from 'next/navigation';
import {XDSCommandPalette} from '@xds/core/CommandPalette';
import {createStaticSource} from '@xds/core/Typeahead';
-import type {XDSSearchableItem} from '@xds/core/Typeahead';
import type {ComponentEntry} from '../generated/componentRegistry';
-
-interface SearchItem extends XDSSearchableItem<{group: string}> {
- id: string;
- label: string;
- auxiliaryData: {group: string};
-}
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
import type {TemplateEntry} from '../generated/templateRegistry';
import {trackSearch} from '../lib/analytics';
+import {
+ buildSearchPaletteItems,
+ getSearchItemKeywords,
+} from './searchPaletteData';
interface SearchPaletteProps {
isOpen: boolean;
@@ -38,67 +35,18 @@ export function SearchPalette({
}: SearchPaletteProps) {
const router = useRouter();
- // Build search items with hrefs embedded in the id for navigation
+ // Component items come from the same grouped registry as the sidebar so
+ // sidebar and command palette navigation stay in lockstep.
const searchSource = useMemo(() => {
- const items: SearchItem[] = [];
-
- for (const entries of Object.values(components)) {
- for (const comp of entries) {
- if (comp.hidden || comp.parentDoc) {
- continue;
- }
- items.push({
- id: `/components/${comp.name}`,
- label: comp.name,
- auxiliaryData: {group: 'Component'},
- });
- }
- }
-
- for (const pkg of packages) {
- const isTheme = pkg.name.includes('theme-');
- // All themes share the single /themes surface — the per-theme
- // dynamic route was removed in favor of state-driven selection.
- // Search results for theme packages all land on /themes with
- // Neutral as the default seed; users browse to the specific
- // theme they want via the sidebar picker.
- items.push({
- id: isTheme ? '/themes' : `/docs/${pkg.name.replace('@xds/', '')}`,
- label: pkg.displayName,
- auxiliaryData: {group: 'Package'},
- });
- }
-
- for (const doc of docTopics) {
- items.push({
- id: `/docs/${doc.topic}`,
- label: doc.title,
- auxiliaryData: {
- group: doc.category === 'guide' ? 'Guide' : 'Foundations',
- },
- });
- }
-
- for (const tmpl of templates) {
- items.push({
- id: `/templates/${tmpl.slug}`,
- label: tmpl.name,
- auxiliaryData: {group: 'Template'},
- });
- }
+ const items = buildSearchPaletteItems({
+ components,
+ packages,
+ docTopics,
+ templates,
+ });
return createStaticSource(items, {
- keywords: item => {
- const kws = [(item.auxiliaryData as {group: string}).group];
- for (const entries of Object.values(components)) {
- const match = entries.find(c => c.name === item.label);
- if (match) {
- kws.push(...match.keywords);
- break;
- }
- }
- return kws;
- },
+ keywords: getSearchItemKeywords,
});
}, [components, packages, docTopics, templates]);
diff --git a/apps/docsite/src/components/componentSidebarData.ts b/apps/docsite/src/components/componentSidebarData.ts
new file mode 100644
index 0000000000..6f78b27252
--- /dev/null
+++ b/apps/docsite/src/components/componentSidebarData.ts
@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {groupedComponents} from '../generated/groupedComponentRegistry';
+import type {
+ ComponentItem,
+ GroupedEntry,
+} from '../generated/groupedComponentRegistry';
+
+export interface ComponentSidebarData {
+ componentItems: ComponentItem[];
+ utilities: Array<{name: string; displayName: string; href: string}>;
+}
+
+/**
+ * Single source of truth for the component sidebar. Other navigation surfaces
+ * that should mirror the sidebar (for example the command palette) should use
+ * this helper instead of independently filtering componentRegistry entries.
+ */
+export function getComponentSidebarData(): ComponentSidebarData {
+ const grouped = groupedComponents['@xds/core'];
+ if (!grouped) {
+ return {componentItems: [], utilities: []};
+ }
+ return {componentItems: grouped.items, utilities: grouped.utilities};
+}
+
+export function flattenComponentSidebarEntries(
+ {componentItems, utilities}: ComponentSidebarData = getComponentSidebarData(),
+): GroupedEntry[] {
+ const entries: GroupedEntry[] = [];
+
+ for (const item of componentItems) {
+ if (item.type === 'entry') {
+ entries.push(item);
+ } else {
+ entries.push(
+ ...item.entries.map(entry => ({
+ type: 'entry' as const,
+ name: entry.name,
+ displayName: entry.displayName,
+ href: entry.href,
+ description: '',
+ })),
+ );
+ }
+ }
+
+ entries.push(
+ ...utilities.map(entry => ({
+ type: 'entry' as const,
+ name: entry.name,
+ displayName: entry.displayName,
+ href: entry.href,
+ description: '',
+ })),
+ );
+
+ return entries;
+}
diff --git a/apps/docsite/src/components/searchPaletteData.ts b/apps/docsite/src/components/searchPaletteData.ts
new file mode 100644
index 0000000000..eaa0fd0d48
--- /dev/null
+++ b/apps/docsite/src/components/searchPaletteData.ts
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {XDSSearchableItem} from '@xds/core/Typeahead';
+import type {ComponentEntry} from '../generated/componentRegistry';
+import type {PackageMeta} from '../generated/packageRegistry';
+import type {DocTopic} from '../generated/docsRegistry';
+import type {TemplateEntry} from '../generated/templateRegistry';
+import {flattenComponentSidebarEntries} from './componentSidebarData';
+
+export interface SearchItemAuxiliaryData {
+ group: string;
+ keywords: string[];
+}
+
+export interface SearchItem extends XDSSearchableItem<SearchItemAuxiliaryData> {
+ id: string;
+ label: string;
+ auxiliaryData: SearchItemAuxiliaryData;
+}
+
+interface SearchPaletteDataInput {
+ components: Record<string, ComponentEntry[]>;
+ packages: PackageMeta[];
+ docTopics: DocTopic[];
+ templates: TemplateEntry[];
+}
+
+function uniqueKeywords(keywords: Array<string | null | undefined>): string[] {
+ return [...new Set(keywords.filter((kw): kw is string => Boolean(kw)))];
+}
+
+export function getSearchItemKeywords(item: SearchItem): string[] {
+ return [item.auxiliaryData.group, ...item.auxiliaryData.keywords];
+}
+
+export function buildSearchPaletteItems({
+ components,
+ packages,
+ docTopics,
+ templates,
+}: SearchPaletteDataInput): SearchItem[] {
+ const items: SearchItem[] = [];
+ const componentLookup = new Map<string, ComponentEntry>();
+
+ for (const entries of Object.values(components)) {
+ for (const comp of entries) {
+ componentLookup.set(comp.name, comp);
+ }
+ }
+
+ for (const entry of flattenComponentSidebarEntries()) {
+ const comp = componentLookup.get(entry.name);
+ items.push({
+ id: entry.href,
+ label: entry.displayName,
+ auxiliaryData: {
+ group: 'Component',
+ keywords: uniqueKeywords([
+ entry.name,
+ entry.displayName,
+ comp?.moduleName,
+ ...(comp?.keywords ?? []),
+ ]),
+ },
+ });
+ }
+
+ for (const pkg of packages) {
+ const isTheme = pkg.name.includes('theme-');
+ // All themes share the single /themes surface — the per-theme
+ // dynamic route was removed in favor of state-driven selection.
+ // Search results for theme packages all land on /themes with
+ // Neutral as the default seed; users browse to the specific
+ // theme they want via the sidebar picker.
+ items.push({
+ id: isTheme ? '/themes' : `/docs/${pkg.name.replace('@xds/', '')}`,
+ label: pkg.displayName,
+ auxiliaryData: {
+ group: 'Package',
+ keywords: uniqueKeywords([pkg.name, pkg.displayName]),
+ },
+ });
+ }
+
+ for (const doc of docTopics) {
+ items.push({
+ id: `/docs/${doc.topic}`,
+ label: doc.title,
+ auxiliaryData: {
+ group: doc.category === 'guide' ? 'Guide' : 'Foundations',
+ keywords: uniqueKeywords([doc.topic, doc.title, doc.category]),
+ },
+ });
+ }
+
+ for (const tmpl of templates) {
+ items.push({
+ id: `/templates/${tmpl.slug}`,
+ label: tmpl.name,
+ auxiliaryData: {
+ group: 'Template',
+ keywords: uniqueKeywords([tmpl.slug, tmpl.name, tmpl.category]),
+ },
+ });
+ }
+
+ return items;
+}