Skip to content

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

TypeScript

feat(cli): discover showcases from external packages (#1920)

Cindy Zhange0ed4fc11f21
diff --git a/packages/cli/src/api/component.mjs b/packages/cli/src/api/component.mjs
index 15b7e17b2a..ea2e2fe583 100644
--- a/packages/cli/src/api/component.mjs
+++ b/packages/cli/src/api/component.mjs
@@ -192,7 +192,7 @@ export async function component(name, options = {}) {
}
if (showcase) {
- const match = await findShowcase(dirName);
+ const match = await findShowcase(dirName, cwd);
if (!match) {
throw new XDSError(`No showcase found for "${name}"`);
}
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index abb3f35f7b..0072351ff1 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -4,7 +4,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {CLI_ROOT} from '../utils/paths.mjs';
+import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
import {XDSError} from './error.mjs';
import {loadConfig} from '../lib/config.mjs';
@@ -91,16 +91,67 @@ async function discoverBlocks() {
return blocks;
}
+/**
+ * Discover blocks from external packages that declare `xds.blocks`.
+ * Same shape as discoverBlocks() output.
+ *
+ * @param {string} [cwd]
+ */
+async function discoverExternalBlocks(cwd = process.cwd()) {
+ const externals = discoverExternalPackages(cwd);
+ const blocks = [];
+
+ for (const ext of externals) {
+ if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
+ const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);
+ for (const docPath of docFiles) {
+ const basename = path.basename(docPath, '.doc.mjs');
+ const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
+ if (!fs.existsSync(tsxPath)) continue;
+ const doc = await loadDocModule(docPath);
+ const relPath = path.relative(ext.blocksDir, path.dirname(docPath));
+ blocks.push({
+ type: 'block',
+ dirName: basename,
+ name: doc?.name || basename,
+ description: doc?.description || '',
+ isReady: doc?.isReady ?? true,
+ aspectRatio: doc?.aspectRatio ?? 1,
+ componentsUsed: doc?.componentsUsed ?? [],
+ isShowcase: doc?.isShowcase ?? false,
+ filePath: tsxPath,
+ docPath,
+ category: relPath,
+ package: ext.name,
+ });
+ }
+ }
+
+ return blocks;
+}
+
+/**
+ * Discover all blocks — core + external packages.
+ * @param {string} [cwd]
+ */
+async function discoverAllBlocks(cwd = process.cwd()) {
+ const [core, external] = await Promise.all([
+ discoverBlocks(),
+ discoverExternalBlocks(cwd),
+ ]);
+ return [...core, ...external];
+}
+
async function discoverAll() {
const [pages, blocks] = await Promise.all([
discoverPages(),
- discoverBlocks(),
+ discoverAllBlocks(),
]);
return [...pages, ...blocks].sort((a, b) => a.name.localeCompare(b.name));
}
-export async function findRelatedBlocks(componentName) {
- const blocks = await discoverBlocks();
+export async function findRelatedBlocks(componentName, cwd) {
+ const blocks = await discoverAllBlocks(cwd);
return blocks.filter(b =>
b.componentsUsed.some(c =>
c.toLowerCase() === componentName.toLowerCase(),
@@ -108,8 +159,8 @@ export async function findRelatedBlocks(componentName) {
);
}
-export async function findShowcase(componentName) {
- const blocks = await discoverBlocks();
+export async function findShowcase(componentName, cwd) {
+ const blocks = await discoverAllBlocks(cwd);
const lc = componentName.toLowerCase();
const showcases = blocks.filter(b => b.isShowcase);
diff --git a/packages/cli/src/commands/external-showcase.test.mjs b/packages/cli/src/commands/external-showcase.test.mjs
new file mode 100644
index 0000000000..7d8f6fc9e7
--- /dev/null
+++ b/packages/cli/src/commands/external-showcase.test.mjs
@@ -0,0 +1,119 @@
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {findShowcase, findRelatedBlocks} from '../api/template.mjs';
+
+// These tests verify that findShowcase and findRelatedBlocks can discover
+// blocks from external packages that declare xds.blocks in package.json.
+
+let tmpDir;
+
+function createFixture() {
+ // Symlink real core package (needed for findCoreDir)
+ const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', 'core');
+ const coreDir = path.join(tmpDir, 'packages', 'core');
+ fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+ fs.symlinkSync(realCoreDir, coreDir);
+
+ // External package with blocks
+ const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
+ const blocksDir = path.join(extDir, 'blocks', 'components');
+
+ // Employee showcase
+ const employeeDir = path.join(blocksDir, 'Employee');
+ fs.mkdirSync(employeeDir, {recursive: true});
+ fs.writeFileSync(path.join(employeeDir, 'EmployeeShowcase.doc.mjs'), `
+export const doc = {
+ type: 'block',
+ name: 'Employee — Profile Card',
+ description: 'Employee profile card with hover preview.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Employee'],
+};
+`);
+ fs.writeFileSync(path.join(employeeDir, 'EmployeeShowcase.tsx'),
+ "'use client';\nexport default function EmployeeShowcase() { return <div>Employee</div>; }");
+
+ // Diff showcase + example
+ const diffDir = path.join(blocksDir, 'Diff');
+ fs.mkdirSync(diffDir, {recursive: true});
+ fs.writeFileSync(path.join(diffDir, 'DiffShowcase.doc.mjs'), `
+export const doc = {
+ type: 'block',
+ name: 'Diff — Link with Hover Card',
+ description: 'Diff link with automatic hover card preview.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Diff'],
+};
+`);
+ fs.writeFileSync(path.join(diffDir, 'DiffShowcase.tsx'),
+ "'use client';\nexport default function DiffShowcase() { return <div>Diff</div>; }");
+ fs.writeFileSync(path.join(diffDir, 'DiffStatusBadges.doc.mjs'), `
+export const doc = {
+ type: 'block',
+ name: 'Diff — Status Badges',
+ description: 'Shows diff status badge variants.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['Diff', 'Badge'],
+};
+`);
+ fs.writeFileSync(path.join(diffDir, 'DiffStatusBadges.tsx'),
+ "'use client';\nexport default function DiffStatusBadges() { return <div>Diff</div>; }");
+
+ fs.writeFileSync(path.join(extDir, 'package.json'), JSON.stringify({
+ name: '@test/ext',
+ xds: {docs: './src', category: 'Common', blocks: './blocks/components'},
+ }));
+
+ // Need src dir for docs (even if empty) since discoverExternalPackages checks it
+ fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
+}
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-showcase-test-'));
+ createFixture();
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('findShowcase() with external packages', () => {
+ it('finds showcase from external package by directory name', async () => {
+ const result = await findShowcase('Employee', tmpDir);
+ expect(result).not.toBeNull();
+ expect(result.name).toBe('Employee — Profile Card');
+ expect(result.filePath).toContain('EmployeeShowcase.tsx');
+ });
+
+ it('finds showcase from external package by componentsUsed', async () => {
+ const result = await findShowcase('Diff', tmpDir);
+ expect(result).not.toBeNull();
+ expect(result.name).toBe('Diff — Link with Hover Card');
+ });
+
+ it('returns null for component with no showcase', async () => {
+ const result = await findShowcase('NonExistent', tmpDir);
+ expect(result).toBeNull();
+ });
+});
+
+describe('findRelatedBlocks() with external packages', () => {
+ it('finds related blocks from external package', async () => {
+ const result = await findRelatedBlocks('Diff', tmpDir);
+ expect(result).toHaveLength(2);
+ const names = result.map(b => b.dirName).sort();
+ expect(names).toEqual(['DiffShowcase', 'DiffStatusBadges']);
+ });
+
+ it('finds cross-package component references', async () => {
+ const result = await findRelatedBlocks('Badge', tmpDir);
+ expect(result.some(b => b.dirName === 'DiffStatusBadges')).toBe(true);
+ });
+});
diff --git a/packages/cli/src/utils/paths.mjs b/packages/cli/src/utils/paths.mjs
index 4077248294..c8a47d9316 100644
--- a/packages/cli/src/utils/paths.mjs
+++ b/packages/cli/src/utils/paths.mjs
@@ -71,9 +71,9 @@ export function findProjectRoot(startDir = process.cwd()) {
* Discover external XDS-compatible packages from node_modules.
* Scans for packages with an "xds" field in their package.json:
*
- * { "xds": { "docs": "./src", "category": "Common" } }
+ * { "xds": { "docs": "./src", "category": "Common", "blocks": "./blocks/components" } }
*
- * Returns array of { name, category, docsDir }.
+ * Returns array of { name, category, docsDir, blocksDir }.
*/
export function discoverExternalPackages(startDir = process.cwd()) {
const externals = [];
@@ -121,6 +121,9 @@ export function discoverExternalPackages(startDir = process.cwd()) {
name: pkg.name,
category: pkg.xds.category || pkg.name,
docsDir: path.resolve(fullPath, pkg.xds.docs),
+ blocksDir: pkg.xds.blocks
+ ? path.resolve(fullPath, pkg.xds.blocks)
+ : null,
});
}
} catch {
diff --git a/packages/cli/src/utils/paths.test.mjs b/packages/cli/src/utils/paths.test.mjs
index e9bfdcebe7..e82c0a03c0 100644
--- a/packages/cli/src/utils/paths.test.mjs
+++ b/packages/cli/src/utils/paths.test.mjs
@@ -83,6 +83,7 @@ describe('discoverExternalPackages', () => {
name: 'xds-charts',
category: 'Data Viz',
docsDir: path.join(extDir, 'src'),
+ blocksDir: null,
},
]);
});
@@ -105,6 +106,7 @@ describe('discoverExternalPackages', () => {
name: '@acme/xds-widgets',
category: 'Widgets',
docsDir: path.join(scopedDir, 'lib'),
+ blocksDir: null,
},
]);
});